1 Disclaimer and Licence

1.1 Disclaimer

1.2 Licence

1.3 Websites

• The main binary_c website is at https://binary_c.gitlab.io/
• binary_c's main git repository is at https://gitlab.com/binary_c/binary_c
• Most binary_c development is communicated through the binary Slack channel binaryslack.slack.com.
• binary_c is on Twitter at https://twitter.com/binary_c_code
• binary_c is on Facebook at https://www.facebook.com/groups/149489915089142
• binary_c is on YouTube at https://www.youtube.com/channel/UCsWzzMdthAs5LMmDnXEqzrg

1.4 Mailing lists and Slack

• We have a Slack workspace for binary_c, the “BinarySlack”, at binaryslack.slack.com.
• The announcements list
  https://groups.google.com/group/binary_c-nucsyn-announce
  This contains major announcements such as significant upgrades to binary_c (or the supporting software)
• The development list
  https://groups.google.com/group/binary_c-nucsyn-devel
  This is more of a discussion list outlining specific changes to physics and technical development of the code(s).

1.5 Conventions

$ cd $HOME
$ ls

#!/bin/bash
# ...
# this is a bash script
export BINARY_C=$HOME/progs/stars/binary_c
cd $BINARY_C
./binary_c version

int x = 1;
x++;
printf(“hello binary_c world x is %d\n”,x);

my $x = 1;
$x++;
print “hello binary_c world x is $x\n”;

x = 1
x += 1
print(f“hello binary_c world x is {x}”)

2 Quick start guide

2.1 Operating system requirements

2.1.1 Linux (Ubuntu 22.04)

wget https://gitlab.com/binary_c/binary_c/-/raw/master/ubuntu_install_binary_c.sh
chmod +x ubuntu_install_binary_c.sh
./ubuntu_install_binary_c.sh

2.1.2 OSX

2.1.3 Windows

2.2 Download and build binary_c

• Required (Do this once) Add to your .bashrc or equivalent shell profile
  

  export BINARY_C=$HOME/progs/stars/binary_c

  
  and restart your shell so that the environment variable BINARY_C is defined.
• Required (Do this once in .bashrc or manually every time) Set up LIBRARY_PATH, LD_LIBRARY_PATH and PATH in .bashrc. For example, add the following to .bashrc if you are using bash,
  

  export LD_LIBRARY_PATH=$HOME/lib:$BINARY_C/src
  export LIBRARY_PATH=$HOME/lib
  export PATH=$PATH:$HOME/.local/bin:$HOME/bin

  
  and restart your shell.
• Optional If you can, install libbsd – this is a system package so requires root access. You will require the development version which contains the various header files, this is usually called libbsd-dev (or similar). libbsd is not required for binary_c but is useful and may speed up the code.
• Probably required Update your meson and ninja,
  

  pip3 install --upgrade meson
  pip3 install --upgrade ninja

  
  
• Probably required If you can, install librinterpolate. binary_c includes a version of librinterpolate as a backup, but it's useful to build and install it so you get the latest version.
  

  mkdir $HOME/lib $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/librinterpolate.git
  cd $HOME/git/librinterpolate
  meson setup --prefix=$HOME --buildtype=release builddir
  ninja -C builddir install

  
  
  Note: you must install librinterpolate if you want to install $binary\_c-python$.
• Optional If you can, install libmemoize. binary_c includes a version of libmemoize as a backup, but it's useful to build and install it so you get the latest version.
  

  mkdir $HOME/lib $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/libmemoize.git
  cd $HOME/git/libmemoize
  meson setup --prefix=$HOME --buildtype=release builddir
  ninja -C builddir install

  
  
• Optional If you can, install libcdict. binary_c includes a version of libcdict as a backup, but it's useful to build and install it so you get the latest version.
  

  mkdir $HOME/lib $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/libcdict.git
  cd $HOME/git/libcdict
  meson setup builddir --prefix=$HOME --buildtype=release
  ninja -C builddir install

  
  
• Required Clone the $master$ branch of binary_c.
  

  export CC=gcc # or the compiler of your choice
  unset CFLAGS
  mkdir -p $HOME/progs/stars/
  cd $HOME/progs/stars
  git clone https://gitlab.com/binary_c/binary_c.git

  
  
• Required Change to the binary_c directory, configure and build both binary_c and its shared library. Note: if builddir already exists, you need to add
  

  --reconfigure

  
  to the Meson command, or delete builddir before this step. Here we build a “release” version of binary_c with full optimization and no debugging support.
  

  cd $BINARY_C
  meson setup builddir --buildtype=release 
  ninja -C builddir binary_c_install 
  cd ..

  
  binary_c is now installed
• Optional You can test binary_c with binary_c-config
  

  cd $BINARY_C
  ./binary_c-config version

  
  which should tell you the binary_c version number.
• Optional If you want to use $binary\_c-python$ to make stellar populations:
  

  export GSL_DIR=`gsl-config --prefix`
  export LD_LIBRARY_PATH=”$HOME/lib:$BINARY_C:$BINARY_C/src” # you may already have set this above
  export LIBRARY_PATH="$LD_LIBRARY_PATH" # you may already have set this above
  export PATH=$HOME/bin:$HOME/.local/bin:$PATH
  cd $HOME/git
  git clone https://gitlab.com/binary_c/binary_c-python.git
  cd binary_c-python
  ./install.sh

  
  

2.3 Running a single- or binary-star system: tbse

• In this file you can set every physical parameter of binary_c, for example the masses and orbital parameters
  

  # stellar masses (solar units)
  M1=6
  M2=0.9
  
  # orbit: 
  # If the period (days) is given, use it. 
  # If the period is zero, use the separation (in Rsun) to calculate the period.
  # (this requires that the masses are already set)
  ORBITAL_PERIOD=0.0
  ORBITAL_SEPARATION=3000.0
  
  # Orbital eccentricity should be in the range 0.0-1.0.
  ECCENTRICITY=0.0

  
  
• You can also override physics by running tbse with subsequent command-line arguments, e.g., to run the default star with a metallicity of $0.004$:
  

  tbse metallicity 0.004

  
  
• Do not run many stars this way because it will be really slow: use $binary\_c-python$ for such a task.

2.4 Running a grid of stars with $binary\_c-python$

• Open the file $BINARY_C/src/python/ensemble.py
• This is an example script that runs binary_c through $binary\_c-python$ to extract ensemble data from a grid of stars.
• You can change parameters in the file, which are set in Python dictionaries, or you can set these when you run the script on the command line.
• Try running the following:
  

  cd $BINARY_C
  ./src/python/ensemble.py r=10 verbosity=1 M1spacing=logM1 ensemble_filter_SCALARS=1 
  outdir=/tmp 

  
  which runs a $10\times 10\times 10$ grid of stars, with some verbose output (to keep you updated every few seconds), a log-spaced grid in $M_1$ and saves the scalar and chemical-yield data to the ensemble in /tmp.

3 Introduction

For many years the study of stellar yields and galactic chemical evolution (GCE) has gone on assuming, mainly for simplicity, that stars are isolated objects (one exception being De Donder and Vanbeveren, 2002). Reality bites deeply into this picture with the observation that most stars are in multiple systems and that many of these systems are interacting. The state of the art in binary star nucleosynthesis is focused on explosive events such as type Ia supernovae and classical novae but other binary star processes contribute to pollution of the interstellar medium. Mass-transfer by Roche-lobe overflow (RLOF) occurs particularly when the stellar radius is growing rapidly and so commonly when one star is on the asymptotic giant branch (AGB).

• The presence of a companion affects evolution by mass loss and gain. Good examples are Roche-lobe overflow caused by interaction between a giant branch or asymptotic giant branch (GB/AGB) star and a main-sequence (MS) star. Truncation of the GB/AGB phase may prevent dredge-up events and hence reduce the amount of nuclear processing material undergoes prior to expulsion to the ISM. Common envelopes generally result and while the detailed physics is unclear it is likely that mass is ejected to the ISM from some of these stars.
• Novae, type Ia supernoave, X-ray bursts, stellar mergers (including neutron-star/black-hole mergers), etc. occur in binaries, as do many tidal disruption events. These may eject material or lead to extra nuclear burning.

• Duplicity: is the star single or binary or perhaps even triple or quadruple?
• Metallicity and, less importantly, initial abundance mix. The initial abundance mix depends on the galactic evolution history and even the solar mixture is somewhat uncertain.
• Initial distributions: What is the IMF? What is the initial distribution for primary mass, secondary mass, separation/period and eccentricity in binary stars?
• Abundance changes at dredge-ups. These changes can depend on the input physics, especially in the case of third dredge-up. Calibration to observations is necessary in this case and leads to the introduction of free parameters to increase the amount of dredge-up. There is also great uncertainty with regard to the s-process isotopes, in particular the size of the C13 pocket during third dredge-up.
• Wind loss rates. Mass loss due to stellar winds is a very dodgy affair - most prescriptions in current use are quite phenomenological and have little regard for actual physics. With this in mind it is important to test a range of prescriptions.
• Common envelope parameters - the parameters ${\lambda }_{CE}$ and ${\alpha }_{CE}$ parameterise our ignorance of this complex process, mainly because the mechanism for driving off the stellar envelope is unclear (magnetic fields? friction? ionization? who knows!). This problem is very much open (Izzard et al., 2012; Ivanova et al., 2013).
• Eddington limit : should this be imposed during accretion processes?
• HBB temperature : somewhat uncertain is the amount of HBB, this can be varied in the model
• Black hole formation : what is the mass of a black hole forming from a given mass progenitor?
• Supernova kicks : is there a kick at SN formation? What is the magnitude/distribution of this kick? Pulsar peculiar velocities give us an idea but are not necessarily the answer to the question.
• Binary induced wind loss (Companion Reinforced Attrition Process - CRAP) - see Chris Tout's PhD. Does the presence of a binary companion increase wind loss rates? What about circularization? (Barium stars are eccentric and have short periods – current theory, and this code, cannot make these stars!)
• Time evolution of the yields. Even if the integrated yield up to (say) 15Gyr from a population of stars is similar when comparing binary and single stars, the time evolution probably is not. For example, nitrogen peaks far more quickly in single than in binary stars because massive ($M>4M_{\odot }$) TPAGB stars in binaries overflow their Roche lobes prior to HBB so C12 cannot be converted into N14.
• Numerical resolution - requires careful consideration!

• First and second dredge-up fitted to the detailed nucleosynthesis models of Karakas et al. (2002).
• A new synthetic model of TPAGB stars (Izzard et al., 2004) in collaboration with Amanda Karakas, Chris Tout and Onno Pols based on the Karakas et al. models. The effects of third dredge-up, the $s$-process, hot-bottom burning (CNO, NeNa and MgAl) and mass loss are included.
• Phenomenological fits to massive and Wolf-Rayet star surface abundances (elemental H, He, CNO, Ne) based on the models of Lynnette Dray (Dray et al., 2003). These were recently complemented by tables from Richard Stancliffe which include all the isotopes up to iron (Stancliffe, private communication, see also Izzard et al., 2006a).
• Supernovae: types Ia, II and Ib/c with yields fitted to published models (Woosley et al., 1986; Livne and Arnett, 1995; Woosley and Weaver, 1995; Iwamoto et al., 1999; Chieffi and Limongi, 2004).
• Nova yields fitted to José and Hernanz (1998).
• $r$-process “yields” (I say this in the loosest possible sense!) from Arlandini et al 1999 and Simmerer 2004.
• Roche-Lobe Overflow and (possible) accretion onto the companion, common-envelope loss contribution to yields.
• Mass loss due to winds and mass gain from a companion.
• Colliding winds.
• Accretion is treated with a two-layer model and thermohaline mixing.
• Mergers.
• SN stripping of companions.
• Planetary orbits.
• Circumbinary discs (Izzard and Jermyn, 2022).
• (With MINT) MS burning of the interior of the star and stellar structure lookup tables.

• Diffusion - nobody plans to work on this!
• "Extra mixing" - dubious although might be the cause of J-stars.
• Common envelope nucleosynthesis - thought not to be important, but you never know.
• WD surface layers - these are very complicated!
• Stellar structure changes caused by rotation. Tricky one this! Not only is the rate of rotational mixing unknown, few stars are thought to rotate this fast. But… these should be included, so let me know if you know a way.
• Probably some other things too.

3.1 Binary_c: tools for stellar evolution and population synthesis

binary_c

The binary_c code itself. This is the core code, written in C, which contains the stellar evolution and nucleosynthesis algorithms.

libbinary_c

The shared library based on binary_c which should be accessed through the binary_c API functions. This works with other languages such as Python and FORTRAN.

$binary\_c-python$

A suite of software to run many stars in a stellar population. If you want to run more than a few stars at once, and combine the results into something useful for science, this is the tool you should use.

4 Installation

4.1 Quick start

4.2 Getting binary_c

4.2.1 Getting the binary_c source code

• the latest stable release or
• the latest version in the master branch.

With git

download the source code from https://gitlab.com/binary_c/binary_c, e.g. from the command line,

git clone https://gitlab.com/binary_c/binary_c.git

or, if you have set up SSH keys on gitlab.com,

git clone git@gitlab.com:binary_c/binary_c.git

If you then want to change to the latest release, you should change to the appropriate branch, e.g.

git checkout releases/2.2.3

As a zip file

You should get the master if you can from https://gitlab.com/binary_c/binary_c/-/archive/master/binary_c-master.zip
or you can either download a release, e.g.,
https://gitlab.com/binary_c/binary_c/-/archive/releases/2.2.3/binary_c-releases-2.2.3.zip
Note that you can change

.zip

to

.tar.bz2

or

.tar.gz

should you prefer a different compression algorithm.

4.2.2 Editing the source code

4.2.3 Getting the Docker image

1. I assume you have installed and signed in to docker. I cannot provide support for Docker!
2. The newest binary_c container should be used. At the time of writing this is robizzard/binary_c:master2.2.3
   Public URL at Docker: https://hub.docker.com/r/robizzard/binary_c
3. Pull the “latest” version with
   

   $ docker pull robizzard/binary_c

   
   or a specific version (in this case 2.2.3) with
   

   $ docker pull robizzard/binary_c:master2.2.3

   
   
4. When you run Docker it inherits your stack settings, which may be too small for binary_c to run. Use
   

   $ --ulimit stack:-1

   
   in your startup command to avoid this.
5. Run it with a command like
   

   $ docker run --ulimit stack=-1 -it robizzard/binary_c:latest /bin/bash --login

   
   this loads a bash shell in the directory of binary_c .
6. Further information can be found in the file
   /home/binary_c/progs/stars/binary_c/doc/README.docker
7. The following bash script allows you to run an X11-enabled terminal with binary_c and binary_grid prebuilt, you have to do nothing more than run them.
   

   #!/bin/bash
   
   ############################################################
   # run binary_c using docker on Linux/Unix
   ############################################################
   
   ############################################################
   # we create a volume in binary_c_persistent : this
   # is a persistent file space that is stored even when
   # binary_c stops
   ############################################################
   docker volume create binary_c_volume >/dev/null
   
   ############################################################
   # Allow connections to our X display
   ############################################################
   XAUTH=$(mktemp)
   xauth nlist $DISPLAY |  sed -e 's/^..../ffff/' | xauth -f $XAUTH nmerge -
   chmod 755 $XAUTH
   
   ############################################################
   # run a bash login shell in the container : 
   # this leaves us in an X-connected shell.
   #
   # Note the chown/chgrp to make the persistent directory
   # writable by the user "binary_c"
   ############################################################
   docker run \
          --name=binary_c \
          -it \
          --rm \
          -e DISPLAY=$DISPLAY \
          --ipc=host \
          --net=host \
          --mount source=binary_c_volume,target=/home/binary_c/binary_c_persistent \
          -v /tmp/.X11-unix \
          -v $XAUTH \
          -v $HOME/.Xauthority:/home/binary_c/.Xauthority \
          robizzard/binary_c:master2.2.3 \
          /bin/bash -c "sudo chown binary_c binary_c_persistent ; sudo chgrp binary_c binary_c_persistent; cat /home/binary_c/progs/stars/binary_c/doc/README.docker; bash --login"
   
   
   
   # to clean the BINARY_C volume run:
   # docker volume rm binary_c_volume
   
   # clean up XAUTH
   rm $XAUTH

   
   

4.3 System Requirements

• Linux-specific requirements are listed in Sec. 4.6.
• OSX-specific requirements are listed in Sec. 4.7.
• Windows-specific requirements are listed in Sec. 4.8.

4.3.1 C compiler

• gcc (the GNU compiler http://gcc.gnu.org/) this comes as standard on most Linux and MacOSX systems and is easily installed on others, and is free software.
• clang (C compiler for LLVM http://clang.llvm.org/) is also free, and may be faster than gcc.
• icc (Intel compiler http://software.intel.com/en-us/articles/intel-compilers/) this costs money but it is probably faster than gcc. Please note, I do not have a copy of icc and building with it is likely to be very slow.

4.3.2 Scripting language(s)

• Python should be installed on your system, please use version 3.8 or later. You will also probably need pip.
• Perl is usually installed on your system, or you can download Perl at www.perl.com. If you want to install your own Perl I recommend Perlbrew. Please try to use a version of Perl that is 5.16 or later: 5.37.5 is currently the latest version and works just fine.

4.3.3 Build tools

pip3 install meson
pip3 install ninja

pip3 install --upgrade meson 
pip3 install --upgrade ninja 

; meson support
(load "~/.emacs-el/meson-mode.el")

4.4 Software libraries

4.4.1 Library locations

$ export LIBRARY_PATH=$HOME/lib:$HOME/otherlibs
$ export LD_LIBRARY_PATH=$HOME/lib:$HOME/otherlibs

• If you are using a non-system GSL, and have a system GSL installed at the same time, you need to make sure the location of the non-system gsl-config is first in your PATH. Try running
  

  $ gsl-config --cflags

  
  and this should, if you have installed GSL in /home/user (which is what is in $HOME), give you something like
  

  -I/home/user/include

  
  otherwise you should do something like
  

  $ export PATH=$HOME/bin:$PATH

  
  to force $HOME/bin/gsl-config to run first.
• If you are using a locally-installed libcfitsio you will need to point pkgconfig to the right place. If you installed with
  

  $ prefix=$HOME

  
  you should do:
  

  $ export PKG_CONFIG_PATH=$HOME/lib/pkgconfig

  
  

4.4.2 Required libraries

• Required Install librinterpolate. This is optional for binary_c, but required for $binary\_c-python$.
  

  export PREFIX=$HOME
  mkdir $HOME/lib $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/librinterpolate.git
  cd $HOME/git/librinterpolate
  meson setup builddir --prefix=$HOME --buildtype release
  cd builddir
  ninja install

  
  

4.4.3 Recommended libraries

• Optional If you plan to modify binary_c you probably want a debugger of some sort. On Linux Valgrind and gdb are both excellent, the former for detecting memory leaks and the latter for backtracing, but both are very powerful and flexible tools. You can run binary_c through both using tbse (e.g. Sec. 12.7).
• Optional You could use ccache to speed up builds. You can usually install this as a system package, or see the ccache homepage.
• Optional If you can, install libmemoize. If you do not, binary_c has an internal version but this may out of date.
  

  export PREFIX=$HOME
  mkdir $HOME/lib $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/libmemoize.git
  cd $HOME/git/libmemoize
  meson setup builddir --prefix=$HOME --buildtype release
  cd builddir
  ninja install

  
  
• Optional If you can, install libcdict (this requires meson and ninja). If you do not, binary_c has an internal version but this may out of date.
  

  export CFLAGS=”-O3 -mtune=generic”
  mkdir $HOME/git
  cd $HOME/git
  git clone https://gitlab.com/rob.izzard/libcdict.git
  cd $HOME/git/libcdict
  meson setup builddir --prefix=$HOME --buildtype release
  cd builddir
  ninja install

  
  

4.5 Configuring and building binary_c

4.5.1 From git

4.5.2 From a zip file or tarball

$ unzip binary_c.zip 
$ tar -xvf binary_c.tar.gz
$ tar -xvf binary_c.tar.bz2

4.5.3 Set up ccache (optional)

$ ccache --set-config=sloppiness=pch_defines,time_macros

# use ccache if available
if [[ -d /usr/lib/ccache ]]; then
    export PATH=/usr/lib/ccache/:$PATH
    export CCACHE_SLOPPINESS=pch_defines,time_macros
fi

4.5.4 Building with Meson

$ meson setup builddir

$ meson setup builddir --buildtype release

$ cd builddir
$ ninja binary_c_install

$ cd ..
$ ./tbse

$ cd ..
$ ./binary_c M_1 10 max_evolution_time 1000 log_filename /dev/stdout

4.5.5 Meson buildtypes

$ meson setup builddir --buildtype release

$ meson setup builddir --buildtype debug

4.5.6 Cleaning the build tree

$ cd builddir
$ ninja clean

4.5.7 Building the shared library libbinary_c

$ cd builddir
$ ninja libbinary_c.so

4.5.8 Building binary_c and libbinary_c, and installing them for $binary\_c-python$

$ cd builddir
$ ninja binary_c_install

4.5.9 Alternative compiler

$ export CC=clang
$ meson setup builddir --buildtype release
$ cd builddir
$ ninja binary_c_install

4.5.10 Existing builddir

$ export CC=clang
$ cd builddir
$ meson --reconfigure --buildtype release
$ ninja binary_c_install

4.5.11 Debugging build

$ meson setup builddir -Dvalgrind=true --buildtype debug
$ ninja binary_c_install

$ meson setup builddir
$ cd builddir
$ ninja binary_c_install

4.5.12 Valgrind build

4.5.13 Accurate floating point build

$ meson setup builddir -Daccurate=true

4.5.14 Generic build, e.g. for HTCondor or Slurm clusters

$ meson setup builddir -Dgeneric=true

4.5.15 Extra libraries

4.5.16 Profile-guided builds

./meson/pgo.sh

4.5.17 Troubleshooting

• If you see compilation errors like
  

  text segment at different address

  
  you need to disable Address Space Layout Randomization (ASLR), see e.g. https://askubuntu.com/questions/318315/how-can-i-temporarily-disable-aslr-address-space-layout-randomization or run
  

  $ echo 0 | sudo tee /proc/sys/kernel/randomize_va_space

  
  (note: this requires root access)

4.6 binary_c on Linux

binutils binutils-dev coreutils debianutils bash zip gcc-12 libgcc-12-dev gdb valgrind gawk python3.10 pipenv kcachegrind meson ninja-build emacs perl libgsl-dev libgslcblas0 global libbsd-dev libiberty-dev libjemalloc-dev zlib1g zlib1g-dev unzip wget curl git jp2a libcfitsio-dev sed gawk pkg-config libc6 libc6-dev patchelf libgpg-error-dev libgpgme-dev swig libcairo2-dev libgirepository1.0-dev autoconf python-dev python3-dev zlib1g-dev

$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1

4.7 binary_c on MacOSX

$ export PATH=/usr/local/opt/coreutils/libexec/gnubin/:/usr/local/bin:$PATH

$ export PREFIX=$HOME/software_sci #THAT IS THE DIRECTORY IN WHICH I PUT BINARY_C (I.E. THE PREFIX USED FOR MESON)
$ export CC=$(which clang)        
$ export LDFLAGS="-L/opt/homebrew/opt/llvm/lib" #NEEDED IN MACOSX
$ export CPPFLAGS="-I/opt/homebrew/opt/llvm/include" #NEEDED IN MACOSX                    
$ export BINARY_C=$HOME/software_sci/binary_c
$ export LIBRARY_PATH=$HOME/software_sci/lib:$BINARY_C/src:$BINARY_C
$ export LIBRARY_PATH=$LIBRARY_PATH:/opt/homebrew/Cellar/cfitsio/4.1.0/lib #ADDED IN ORDER TO LET THE MACOSX UNDERSTAND WHERE CFITSIO IS LOCATED
$ export LD_LIBRARY_PATH=$LIBRARY_PATH
$ export DYLD_FALLBACK_LIBRARY_PATH=$LIBRARY_PATH #NEEDED IN MACOSX
$ export GSL_DIR='gsl-config --pref'
$ export PATH=$PATH:$HOME/software_sci/bin:$HOME/.local/bin                         
$ export PATH="/opt/homebrew/opt/llvm/bin:$PATH" #NEEDED IN MACOSX
$ export PATH=/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH #NEEDED IN MACOSX

4.8 binary_c on Windows

4.9 binary_c on VirtualBox

• Download and install VirtualBox from https://www.virtualbox.org/. You need to install VirtualBox and the VirtualBox extensions pack.
• Download the Ubuntu image from https://releases.ubuntu.com/. The current 22.04 image is at https://releases.ubuntu.com/22.04/.
• Run VirtualBox and go to Machine->New, where you have to enter a name for the machine and various other things like a user name and password. I assume both the user and password are set to binary_c.
• You should select as much RAM and CPU power as you can spare. Usually you require 20-25GB of disk space, at least. Most importantly, select the ISO image to be the Ubuntu image you downloaded just now. Start the installation by clicking Next repeatedly, filling in the boxes as you see fit.
• The installation takes a little while, but when it is done log in to the new virtual machine (VM) using the name and password you chose. Once your desktop loads, click “Show applications”, the grid icon in the bottom-left corner, and then choose the Terminal. In the terminal run
  
  

  $ su

  
  to become super user, using your chosen password. Now put your user (I assume you are binary_c) in the sudoers list and exit “super-user mode”.
  

  adduser binary_c sudo
  exit

  
  
• Restart the virtual machine, then log in and run the terminal again.
• In the VirtualBox menu click Devices -> Insert Guest Additions CD image
• In the terminal, run
  

  $ cd /media/binary_c/VBox_GAs_7.0.2
  $ sudo ./VBoxLinuxAdditions.run 

  
  
• Wait for the installation to finish, log out and restart the virtual machine, and re-enter the terminal
• In the VirtualBox menu, click Devices->Shared Clipboard->Bidirectional so you can copy paste the following commands into the terminal
• Run
  

  wget https://gitlab.com/binary_c/binary_c/-/raw/master/ubuntu_install_binary_c.sh
  chmod +x ubuntu_install_binary_c.sh
  ./ubuntu_install_binary_c.sh

  
  and follow the on-screen prompts to install binary_c, support libraries and $binary\_c-python$. When asked how to install binary_c, use the https option unless you have set up SSH keys (probably you haven't).
• If there are errors installing $binary\_c-python$, try opening a new terminal and then
  

  cd git/binary_c-python
  ./install.sh

  
  

5 Evolving single and binary stars

5.1 Running one star with “test binary star evolution”: tbse

$ ./tbse

# Initial primary mass
M1=6
# Initial secondary mass
M2=3
# Initial orbital period (days) 
ORBITAL_PERIOD=100
# Initial eccentricity
ECCENTRICITY=0.2
# (Initial) Metallicity
METALLICITY=0.02
# Maximum evolution time (MYr)
MAX_EVOLUTION_TIME=16000

MAGNETIC_BRAKING_ALGORITHM=0
MAGNETIC_BRAKING_ALGORITHM=MAGNETIC_BRAKING_ALGORITHM_HURLEY_2002

PRE_MAIN_SEQUENCE=True
PRE_MAIN_SEQUENCE_FIT_LOBES=False

LOG_FILENAME=”/tmp/c_log2.out”

$ tbse help

$ ./binary_c help 

$ ./binary_c help <string>

./binary_c help magnetic_braking_algorithm
binary_c help for variable : magnetic_braking_algorithm <Integer>

Algorithm for the magnetic braking angular momentum loss rate. 0 = Hurley et al. 2002, 1 = Andronov, Pinnsonneault and Sills 2003, 2 = Barnes and Kim 2010, 3 = Rappaport 1983 

Available macros:

MAGNETIC_BRAKING_ALGORITHM_HURLEY_2002 = 0
MAGNETIC_BRAKING_ALGORITHM_ANDRONOV_2003 = 1
MAGNETIC_BRAKING_ALGORITHM_BARNES_2010 = 2
MAGNETIC_BRAKING_ALGORITHM_RAPPAPORT_1983 = 3

5.2 tbse commands

tbse echo

This outputs (to stdout) the arguments that would have been sent to binary_c.

tbse_echolines

As tbse echo but in a single line of output. Newlines are converted to \n.

tbse args

Ignores settings in the tbse file and runs only with the extra arguments given on the command line.

tbse arglines

As tbse args but in a single line of output. Newlines are converted to \n.

tbse debug

This runs binary_c with the gdb debugger

tbse gdb

This runs binary_c with the gdb debugger

tbse valgrind

This runs binary_c through Valgrind's memcheck tool to detect memory leaks. Remember to use the flag -Dvalgrind=true when running meson.

tbse valgrind_args

This shows the command-line arguments that are passed to Valgrind and then exits.

tbse massif

This runs binary_c through Valgrind's massif heap checker.

tbse callgrind

This runs binary_c through Valgrind's callgrind tool. Hint: process the output through kcachegrind.

tbse cachegrind

This runs binary_c through Valgrind's cachegrind tool.

tbse ptrcheck

This runs binary_c through Valgrind's ptrcheck tool (note: this tool no longer seems to exist).

tbse sgcheck

This runs binary_c through Valgrind's sgcheck tool (note: this tool no longer seems to exist).

tbse drd

This runs binary_c through Valgrind's drd tool.

tbse gprof

This runs binary_c through gprof, the GNU profiler.

tbse gprof_lines

This runs binary_c through gprof, the GNU profiler, doing line-by-line accounting.

tbse gprof_with_stdout

This runs binary_c through gprof, the GNU profiler, showing stdout.

tbse pgo

Profile guided optimization. This option is deprecated. Please use the meson/pgo.sh script instead.

tbse bug

This runs binary_c and outputs information which is suitable for reporting a bug to Rob.

tbse multicore

This runs binary_c on many CPU cores at once. Exits immediately on failure, so this is useful for testing e.g. Monte carlo kicks.

tbse multicore_valgrind

As tbse_multicore but using Valgrind.

tbse <filename>

This runs the set of arguments specified in the file given by filename.

tbse clip

Runs binary_c and saves the output to the clipboard (requires xclip).

5.2.1 Testing many (random) systems

$ cd $BINARY_C
$ nice -n +19 ./src/perl/scripts2/test_random.pl threads=cpu newlogs logtimes updatetime=0.25 sleeptime=0.25 valgrind

nice -n +19

to make sure we only use idle CPU cycles

threads=cpu

this uses $N-1$ threads, where $N$ is the number of CPU cores (thus leaves one for managing the runs)

newlogs

Makes a new log file in $HOME/binary_c_test_random.log

logtimes

Makes a file $HOME/binary_c_test_random.logtimes containing data that tells us how long each system takes to run

updatetime=0.25

Number of seconds between updating the screen

sleeptime=0.25

Internal sleep time before checking things

valgrind

Run binary_c through valgrind (warning will be slow, but thorough)

6 Making populations of stars with $binary\_c-python$

• https://gitlab.com/binary_c/binary_c-python
• https://pypi.org/project/binary_cpython/

• https://gitlab.com/binary_c/binary_c-python/-/tree/master/examples

• https://gitlab.com/binary_c/binary_c-python/-/blob/master/papers/joss/paper.pdf

7 The binary_c ensemble

This section describes the binary_c population ensemble output. This is a standard method by which you can access a statistical description of a stellar population in the popular JSON format, suitable for fast import into third-party tools and other programming languages.

7.1 The population ensemble

From version 2.17, binary_c has a standard output form, the population ensemble. The ensemble is built as an associative array, using a hash table

3

https://en.wikipedia.org/wiki/Hash_table

, known as a “hash” in Perl and “dictionary” in Python, using the libcdict library

4

https://gitlab.com/rob.izzard/libcdict

.

7.2 Building binary_c with the ensemble

Usually the ensemble is built in, but is turned off by default. The following are set in binary_c_parameters.h:

#define STELLAR_POPULATIONS_ENSEMBLE
#define STELLAR_POPULATIONS_ENSEMBLE_SPARSE
#define STELLAR_POPULATIONS_ENSEMBLE_ND
#define STELLAR_POPULATIONS_ENSEMBLE_DEFAULT FALSE
#define STELLAR_POPULATIONS_ENSEMBLE_DEFER_DEFAULT FALSE
#define STELLAR_POPULATIONS_ENSEMBLE_LOGTIMES_DEFAULT FALSE
#define STELLAR_POPULATIONS_ENSEMBLE_DT_DEFAULT 1.0
#define STELLAR_POPULATIONS_ENSEMBLE_LOGDT_DEFAULT 0.1
#define STELLAR_POPULATIONS_ENSEMBLE_STARTLOGTIME_DEFAULT 0.1

7.3 Enabling ensemble output

You can turn on the ensemble using the Boolean argument ensemble or by setting
stardata->preferences->ensemble, e.g.,

$ ./binary_c ... ensemble True

• Remember True can also be TRUE, T, t or 1, while False can also be FALSE, F, f or 0.

7.3.1 Finer control of ensemble output

The full ensemble is a lot of data, so you have options to filter which output is constructed and output. A list of filters is in

stardata->preferences->ensemble_filters[ENSEMBLE_FILTER_NUMBER_OF_FILTERS]

where the index is defined in X-macros in src/ensemble/ensemble_macros.def. You can obtain a list of these with

./binary_c version |grep 'Ensemble filter'

By default, these are set to TRUE which means there is a lot of output. You may want to be more selective, otherwise – particularly if you are multithreading – you will require a lot of system memory.

• To disable all sections of the ensemble, use
  

  $ ensemble_filters_off True

  
  
• To then turn on some of the filters, use, e.g.,
  

  $ ensemble_filter_ORBIT True

  
  
• If you only want to turn off one filter, do not use ensemble_filters_off, instead set the filter to FALSE, e.g.,
  

  $ ensemble_filter_MERGED False

  
  
• Note that the final part of ensemble_filter_MERGED can be either a macro, as
  

  #defined

  
  above, or the corresponding index. For example, these are identical,
  

  $ ensemble_filter_ORBIT True

  
  
  

  $ ensemble_filter_7 True

  
  

7.4 Ensemble output

libcdict can output its cdict variable in JSON format

5

https://en.wikipedia.org/wiki/JSON

. This is human-readable, easy to parse in other languages

6

https://www.json.org/json-en.html

(e.g. Perl, Python, C, C++, Java, Javascript, …).

When you output from binary_c to the command line, output looks something like,

    "HRD" : {
        "[C/Fe]" : {
            "-5e-2" : {
                "logTeff" : {
                    "3.65e0" : {
                        "logL" : {
                            "3.5e-1" : "7.271832039003311e1",
                            "4.5e-1" : "1.439654435074208e2",
                            "5.5e-1" : "1.1262333695232519e2",
                             ...

but when output is to a buffer, e.g. for parsing by \binary_cpython, the whitespace is omitted.

7.4.1 Deferred output

When you, or software such as \binary_cpython, run multiple stars, the default behaviour is to output a chunk of JSON after each star is run. Perhaps this is what you want, but perhaps instead you want to simply add the output of each star and only output when the final star is run. This reduces communications overheads, for example. To do this, set,

ensemble_defer True

You can test this with the tbse script, e.g.,

$ tbse repeat 10 random_systems True ensemble True ensemble_defer True

The ensemble JSON is output when the ensemble memory is freed, which only happens – if ensemble_defer is True – at the end of the run.

7.5 Adding to or changing the ensemble

While the ensemble outputs a lot of data, you will probably want something in the ensemble that's not currently there. The ensemble is set in src/ensemble/ensemble_log.c and the other files in src/ensemble/ (which are called from

ensemble_log()

) and you will need to change at least this file.

7.5.1 Before you start

The Set_ensemble… macros look for two variables, p and dtp, as well as the ubiquitous stardata,

• p This is usually the probability.
• dtp This is usually the timestep multiplied by the probability.

So if you are doing ensemble logging, you should have two lines of code at the top of your function that usually look like this

const double p = stardata->model.probability;
const double dtp = stardata->model.dt * p;

In ensemble_log(), you should use lineardt instead of stardata->model.dt, although this is already set up for you.

Some may ask, why not use the values in stardata directly? Well, you may want to do something else , and the above setup gives you the freedom to do so.

7.5.2 Adding to the ensemble cdict

The cdict itself is stored in stardata->model.ensemble_cdict which is of type struct cdict_t *. You can, of course, set and update the cdict variables using the libcdict API directly, but please do not do this. Instead, use the two macros Set_ensemble_count and Set_ensemble_rate.

• Set_ensemble_count allows you to count the number of types of stars. The weighting applied is $\delta t\times p$ where $\delta t$ is the timestep and $p$ is the system's probability.
• Set_ensemble_rate allows you to count the rate of events. The weighting applied is $p$, the system's probability. You should use Set_ensemble_rate for instantaneous events, such as mergers, supernovae and initial conditions (e.g. the initial mass function, which is instantaneous as it occurs only at exactly $t=0$).

The arguments to the above macros define a nested location in the ensemble hash. For example, the initial mass function is set with the following call.

Foreach_star(star)
{
     if(born_binary == FALSE)
     {
           Set_ensemble_rate(
                 "distributions",
                 "initial log mass : label->dist",
                 "single",
                 "log mass",
                 (double)Bin_data(Safelog10(star->mass),0.1)
             );
     }
}

The nested location is

"distributions" : "initial log mass : label->dist" : "single" : "log mass"

which defines a cdict (“log mass”) in a cdict (“single”) in a cdict ("initial log mass : label->dist", this is called the label cdict, see Sec. 7.8) in a cdict (“distributions”) in the root cdict, which you cannot change (“ensemble_cdict”).

The final variable in the list is the data, in this case the logarithm of the stellar mass, binned to the nearest $0.1M_{\odot }$ using Bin_data(). You should cast the result of Bin_data() to

(double)

where necessary: libcdict has to otherwise guess the data type, which is notoriously difficult in C, and it may get it wrong (or set it differently using a different compiler or compiler version).

In the above, we use Safelog10() to calculate the log of star->mass: this caps the value of star->mass to avoid

log(0)

.

7.5.3 Binned data

Please, remember to bin your data. In the above call to set the initial mass function, the masses are binned to the nearest $0.1M_{\odot }$. If you fail to bin data, remember the number of floating point values is large enough

7

Around $10^{39}$. https://jameshoward.us/2015/09/09/how-many-floating-point-numbers-are-there/

to fill your RAM many times over – at which point your code will crash (perhaps along with other software running on your machine).

You can use the

Bin_data(x,w)

macro to bin data, where $x$ is the data and $w$ is the bin width.

7.5.4 Time

You should use the variable T in src/ensemble/ensemble_log.c as the time, e.g.,

const double CFe = nucsyn_elemental_square_bracket("C","Fe",
                                                   Xsurf,
                                                   stardata->common.Xsolar,
                                                   stardata);
const double CFe_binned = Bin_data(CFe,0.1);
Set_ensemble_count(
    "distributions",
    "(C)EMP period vs [C/Fe] : label->t->dist",
    "all",
    "time",(double)T,
    "[C/Fe]",(double)CFe_binned);

T is not stardata->model.time, it is the appropriately binned output time, see 7.7.

7.5.5 Fixed values

Sometimes you just want to set a value in the ensemble, rather than something modulated by the timestep or probability. You can do this with Set_ensemble_value, e.g.,

Set_ensemble_value("useful information",
                   "my code version",(double)1.2345
                   ); 

You can also append to such a value, e.g. the following adds $1$ to the above-set $1.2345$,

Set_ensemble_append("useful information",
                   "my code version",(double)1
                   ); 

7.5.6 Mean values

It is possible to log mean values also. This is something more of a challenge, because to calculate a mean the ensemble algorithm must sum a property, and then divide by a denominator. You can choose the denominator.

struct cdict_entry_t * const denominator =
    Set_ensemble_denominator("IRAS",
                             "denominator"
                            );
    Set_ensemble_mean(denominator,
                      "stellar data",
                      "star 0 mean mass",(double)stardata->star[0].mass
                      );

The denominator is the sum of timesteps multiplied by probability, which is just the equivalent total number count. This data must be passed to each Set_ensemble_mean() call.

Now, when is the normalization (division by denominator) done? It is done once when the JSON is output at the end of the run. Internally, when you set the denominator, the ensemble_apply_denominator() function is set in the cdict entry, then this is called by the JSON function, which proceeds to detect the callback in the cdict entry so the normalization cannot happen twice.

7.6 Processing the ensemble

The ensemble has a number of distinct sections, which may change depending on which output you decide to allow. Some examples are:

scalars

These are simple counts or rates expressed as a function of time. The labels for each are of the type ENSEMBLE_<name> which are defined in ensemble_1d.h. These are based on the legacy ensemble that was used for years from libcdict was introduced.

number_counts

These are number counts as a function of time that where not in the legacy ensemble, e.g. because they are multidimensional, such as a count of the numbers of stars of different stellar_types.

distributions

These are multidimensional distributions, either as a function of time or integrated through time (equivalent to assuming a constant star formation rate).

HRD and HRD(t)

These are special distributions, of $logL$ or $logg$ vs $log{T}_{eff}$, they are Hertzsprung-Russell and/or colour-magnitude diagrams, and nested subdata. See ensemble_HRD.c.

7.7 Times of outputs

The variable T should be used in src/ensemble/ensemble_log.c to set the time of output. This is actually the binned time, which is set by the ensemble timestep. You can use either the time itself, $t/Myr$, or ${log}_{10}\left(t/Myr\right)$. You can choose to use linear or log time.

Linear time

is set by default. The ensemble_dt binary_c argument set the timestep in Myr.For example,

binary_c ... ensemble_dt 100

Logarithmic time

is turned on with ensemble_logtimes with a timestep set by ensemble_logdt. You will also have to set ensemble_startlogtime to define a time when logging stars, otherwise logging will start at $t=0$ corresponding to ${log}_{10}t=-\infty$. For example,

binary_c ... ensemble_logtimes True ensemble_logdt 0.1 ensemble_startlogtime 0.1

Remember, the memory required to store data and the runtime increases as you shorten the timestep. Especially when running on cluster nodes, you will want to experiment with different timesteps to acquire the accuracy you require with the least use of resources.

7.8 Labels for automatic data processing

The ensemble examples above define labels (“metadata”) for each distribution which can be used for automatic data processing (see Sec. 7.11). For example, in the following,

Set_ensemble_count(
    "distributions",
    "log luminosity : label->dist",
    "all resolved",
    "log luminosity",(double)luminosity_binned
    );

we have a label

"log luminosity : label->dist"

. This is a distribution of number of stars binned by log luminosity. The label is given metdata which describes the data format: label->dist, i.e. a label then a distribution. In this case, the label is

“all resolved”

and the distribution is

"log luminosity",(double)luminosity_binned

.

The equivalent section of the ensemble JSON output is:

{
   “distributions” : {
      "log luminosity : label->dist" : {
            "all resolved" : {
                "log luminosity" : {
                    "-4.75e0" : "6.428191018390589e2",
                    "-4.65e0" : "1.573166303524993e3",
                    "-4.55e0" : "1.4997031226712315e3",
                    "-4.45e0" : "1.293876996317942e3",
                    "-4.35e0" : "1.0962803892305492e3",
                    "-4.25e0" : "9.204727786665062e2",
                    ...
                }
            }
        }
    }
}

7.8.1 Time dependence

You can include a time dependence with label->t->dist, e.g.,

Set_ensemble_count(
    "distributions",
    "log luminosity(t) : label->t->dist",
    "all resolved",
    "time",(double)T,
    "log luminosity",(double)luminosity_binned
    );

7.8.2 Integer labels

You can define labels of the form Star 0 or Star 1, i.e. integer labels, as follows,

Set_ensemble_count(
    "distributions",
    "log luminosity : labelint->dist",
    "star",(int)i,
    "log luminosity",(double)luminosity_binned
    );

7.8.3 Maps

2D maps can be defined as follows. This sets up a map called merged log masses with abscissa ($x$-axis) primary and ordinate ($y$-axis) secondary:

if(newly_merged)
{
    Set_ensemble_rate(
        "distributions",
        "merged log masses : map",
        "primary",
        (double)Bin_data(
            log10(Max(stardata->previous_stardata->star[0].mass,
                      stardata->previous_stardata->star[1].mass)), 0.1),
        "secondary",
        (double)Bin_data(
            log10(Min(stardata->previous_stardata->star[0].mass,
                      stardata->previous_stardata->star[1].mass)), 0.1)
        );
}

Because we want to output the masses of the stars just prior to them merging, we use the data from stardata->previous_timestep. The masses are binned to the nearest $0.1M_{\odot }$ and their logarithms are the values of the location in the map. We use Set_ensemble_rate() because mergers are treated as instantaneous events.

You can nest a 2D map at any location you like.

7.9 The ensemble manager: making stellar population ensembles

You can use the Ensemble Manager, src/python/ensemble_manager.py, to launch and control stellar population ensembles in an automated way using inlists. Inlists are files which contain the input parameters to define one or more stellar populations.

Warning: the ensemble manager is considered experimental code. It works, but there are likely to be bugs, please use it and report them!

• The ensemble manager automatically handles running many stellar populations on your HPC cluster (with Slurm or Condor).
• The ensemble manager stores details of its various ensembles in an SQLite file ensembles.sql. This is very easy to probe using Python and allows very fast analysis of grids of models.
• Ensembles are each stored in their own directory identified with a UUID. You can find details of each ensemble in the db_chunk_JSON file should you not be able to probe ensembles.sql.

7.9.1 Ensemble manager commands

• To run anything to do with a grid of ensembles, run with the inlist as the first argument
  

  ensemble_manager.py [comamnd] <inlist>

  
  
• You can find some example inlists in $BINARY_C/src/inlists.
• You can do a dry run by setting the ENSEMBLE_MANAGER_DRY_RUN environment variable.
• Launch a grid with
  

  ensemble_manager.py <inlist> launch

  
  
• Stop running jobs with
  

  ensemble_manager.py stop <inlist> stop (UUID|all)

  
  where you can choose columns to show (by default show them all)
• Update the database
  

  ensemble_manager.py stop <inlist> update

  
  
• Obtain ensemble status with
  

  ensemble_manager.py stop <inlist> status [columns]

  
  
• Obtain ensemble long-format status with
  

  ensemble_manager.py stop <inlist> longstatus

  
  
• Show help
  

  ensemble_manager.py help

  
  
• Automatically make plots
  

  ensemble_manager.py makeplots [force]

  
  where if you also include the force argument all plots will be remade even if they already exist.

7.9.2 Environment variables

• BINARY_C Points to the root binary_c directory. This must be set.
• ENSEMBLE_MANAGER_DIR The directory in which the database, and folders containing generated ensemble data, is to be stored. Defaults to: $HOME/data/populations-<binary_c_version>-<git_revision>-<project> where the binary_c_version is given by binary_c-config (e.g. 2.2.2), the git revision is like 5845:20220122:2b57e488e where the first number is the commit number, the second the date and the third is the commit MD5. The -<project> is set by self.runtime_vars['miscellaneous']['project'] and is ignored if this variable is set to None.
• ENSEMBLE_MANAGER_SCRIPT The script to be run to make ensemble data. Defaults to $BINARY_C/src/python/ensemble.py
• ENSEMBLE_MANAGER_PLOTSCRIPT The script to be run to plot an ensemble. Defaults to $BINARY_C/src/python/ensemble_plotter_threaded.py
• ENSEMBLE_MANAGER_DRY_RUN When set, launch commands do nothing but do report what they would have done, i.e. a dry run.
• ENSEMBLE_MANAGER_INLIST_PATHS By default, we look at the inlist's full path, and also in $BINARY_C/src/inlist and $BINARY_C/src/python, for the inlist. You can specify a custom set of paths in $ENSEMBLE_MANAGER_INLIST_PATHS (separated by colons in the normal manner).
• ENSEMBLE_MANAGER_WRONG_REPO_WARNING If set, disable the warning that is given when the git repository revision does not match that of the currently-built binary_c.

7.10 ensemble.py: running individual stellar-population ensembles

Use the src/python/ensemble.py script to generate individual stellar-population ensembles using \binary_cpython . For example,

src/python/ensemble.py r=10 metallicity=0.0001 logdt=0.1 tstart=0.1 verbosity=1 num_cores=24

runs a population with ensemble output every $logt=0.1$ starting at $0.1Myr$, metallicity $Z=10^{-4}$ on 24 threads using a $10\times 10\times 10$ grid. The output is put in /tmp/ by default in ensemble_output.json.bz2. Note: the output is bzipped by default, you can unzip with

$ bunzip2 <file>

.

There are many population options, such as initial distributions and stellar physics, which you can change in the script.

7.10.1 Ensemble JSON format

The ensemble_output.json file has contents like,

{
   "ensemble" : {
      "distributions" : {
         "initial log luminosity : label->dist" : {
            "all resolved" : {
               "log luminosity" : {
                  "-0.05" : 0.0103126232202109,
                  "-0.15" : 0.0163602303936111,
                  "-0.25" : 0.0159375218663686,
                  ...

which is the standard JSON output embedded in the

“ensemble”

. You can process this data yourself, e.g. with Perl use the JSON::Parse module

8

https://metacpan.org/pod/distribution/JSON-Parse/lib/JSON/Parse.pod

, or with Python use the json module

9

https://docs.python.org/3/library/json.html

, or use the plot_ensemble.pl script as described in the following section to have everything done and plotted for you.

7.11 Automatic data processing

You can use the binary_c ensemble viewer, available at https://gitlab.com/binary_c/binary_c_ensemble_viewer, to make plots from ensemble data.

Figure 1:

CO-CO merger rate as a function of time.

Figure 2:

${}^{58}Co$ yield rate as a function of time.

Figure 3:

Theoretical Hertzsprung-Russell diagram ($logL$ vs $log{T}_{eff}$) as a function of time.

8 binary_c API

8.1 Naming conventions

• Names of functions in the binary_c API start with binary_c_
• Functions are declared with the attribute binary_c_API_function
• The binary_c structure types
  • stardata_t
  • star_t
  • preferences_t
  • store_t
  • tmpstore_t
  • model_t
  • common_t
  • etc.
  should be declared in external code as
  • libbinary_c_stardata_t
  • libbinary_c_star_t
  • libbinary_c_preferences_t
  • libbinary_c_store_t
  • libbinary_c_tmpstore_t
  • libbinary_c_model_t
  • libbinary_c_common_t
  • libbinary_c_…
  This avoids name clashes with the functions of other libraries.

8.1.1 binary_c macros

RESTRICT

This is set to __restrict__ or a suitable equivalent when available (this depends on the compiler).

binary_c_API_function

This is set to __attribute__ ((visibility("default"))) which is standard for exporting functions to shared libraries with gcc (and presumably clang). I have not yet investigated the equivalent for other compilers.

8.1.2 binary_c headers

8.2 Using the API

$ gcc ... -lbinary_c ...

$ binary_c-config libs

-lc -lgsl -lgslcblas -lm -lbacktrace -lbfd -lbsd -liberty -ljemalloc -lmemoize -lrinterpolate -lcdict

8.2.1 In C

8.2.2 Macro clashes

#pragma push_macro("Max")
#pragma push_macro("Min")

#undef Max
#undef Min

#include "binary_c.h"

/* ... your subroutines go here ... */


#undef Max
#undef Min

#pragma pop_macro("Min")
#pragma pop_macro("Max")

8.2.3 In C++

8.2.4 In FORTRAN

• Only the argstring interface works (no argc and argv)
• Remember to put a NUL character at the end of the argstring with char(0)
• There is a special function binary_c_fortran_api_stardata_info which can extract some data from a stardata struct. You must write code in C to extract the data, because FORTRAN knows little about C structures. This code is meant as an example: you can always write your own function and export it to your binary_c shared library with the binary_c_API_function macro.

program binary_cinfortran
  use iso_c_binding
  implicit none
  character (len=1024) :: argstring   
  character (len=1024) :: format_string
  type(c_ptr),pointer :: stardata_pointer,store_pointer
  type(c_ptr),target :: stardata,store
  stardata_pointer => stardata
  store_pointer => store
  stardata_pointer = C_NULL_PTR
  store_pointer = C_NULL_PTR

  format_string = '( "binary_c M_1 ",E10.3," M_2 ",E10.3," metallicity ",E10.3," orbital_period ",E10.3," eccentricity ",E10.3," max_evolution_time ",E10.3,A)'
  write(argstring,format_string) 10.d0,5.d0,1d6,0.d0,0.02d0,15000d0,char(0)
  
  call binary_c_fortran_api_new_system(stardata_pointer,C_NULL_PTR,C_NULL_PTR,store_pointer,argstring)
  call binary_c_fortran_api_evolve_for_dt(dt,stardata_pointer) 
  call binary_c_fortran_api_free_memory(stardata_pointer,1,1,1)

end program

8.2.5 In Perl

8.2.6 In Python

8.3 Standard functions

8.3.1 binary_c_new_system

void binary_c_API_function binary_c_new_system(
     struct libbinary_c_stardata_t ** stardata,
     struct libbinary_c_stardata_t ** previous_stardata,
     struct libbinary_c_preferences_t ** preferences,
     struct libbinary_c_store_t ** store,
     char ** argv,
     int argc);

• stardata must be a pointer to a libbinary_c_stardata_t struct pointer. The memory for the stardata is allocated by this function.
• previous_stardata is usually NULL, in which case space for it is allocated. If non-NULL, it must point to a previously allocated libbinary_c_previous_stardata_t struct.
• preferences is allocated and set up if NULL, or should be a pointer to a pointer to a previous allocated libbinary_c_preferences_t struct.
• store must be a pointer to a libbinary_c_store_t struct pointer which is empty and NULL, or a pointer to a pointer to a previously allocated libbinary_c_store_t struct. This feature enables you to make the store only once, but call binary_c_new_system repeatedly with it, thus saving a lot of CPU time.
• store is a pointer to a libbinary_c_persistent_data_t struct pointer which, if NULL, is allocated. This enables you to store data between binary_c runs.
• argv and argc are, if argc is not -1, a set of arguments identical in format to the standard C command line arguments.
  Alternatively, set argc to -1 then argv can be a pointer to a string containing a set of arguments (which must start with the word “binary_c” as this would be the first argument in the standard C format). These are split in binary_c and parsed as usual.

    struct libbinary_c_stardata_t * stardata = NULL;
    struct libbinary_c_store_t * store = NULL;
    struct libbinary_c_persistent_data_t * persistent_data = NULL;

	char * argstring = "binary_c M_1 10 M_2 5 orbital_period 100 eccentricity 0.0 metallicity 0.02";

    binary_c_new_system(&stardata,
                        NULL,
                        NULL,
                        &store,
                        &argstring,
                        &persistent_data,
                        -1);
    /* ... */

8.3.2 binary_c_evolve_for_dt

int binary_c_API_function binary_c_evolve_for_dt(struct libbinary_c_stardata_t * const stardata,
                                                 const double dt);

• stardata is defined previously (Sec. 8.3.1)
• dt is the number of MYr (megayears, $1Myr=10^{6}years$)

8.3.3 binary_c_buffer_info

void binary_c_API_function binary_c_buffer_info(struct libbinary_c_stardata_t * RESTRICT const stardata,
                                                char ** const buffer,
                                                int * size);

• stardata is defined previously (Sec. 8.3.1)
• buffer is a pointer to a char* which points to binary_c 's internal buffer. Any changes you make to the contents of buffer thus also change binary_c 's internal buffer.

8.3.4 binary_c_error_buffer

void binary_c_API_function binary_c_error_buffer(struct stardata_t * RESTRICT const stardata,                                                                                                           char ** const error_buffer)

• stardata is defined previously (Sec. 8.3.1)
• error_buffer is a pointer to a char** which points to a pointer to binary_c 's internal error buffer.
• Unlike the normal buffer defined above, this buffer is of fixed size so you don't have to worry about its length.

8.3.5 binary_c_buffer_empty_buffer

void binary_c_API_function binary_c_buffer_empty_buffer(struct stardata_t * RESTRICT const stardata); 

• stardata is defined previously (Sec. 8.3.1)

8.3.6 binary_c_free_store_contents

void binary_c_API_function binary_c_free_store_contents(struct libbinary_c_store_t * RESTRICT const store);

•  store is defined previously (Sec. 8.3.1)

8.3.7 binary_c_free_memory

void binary_c_API_function binary_c_free_memory(struct stardata_t ** RESTRICT const stardata,
                                                const Boolean free_preferences,
                                                const Boolean free_stardata,
                                                const Boolean free_store,
                                                const Boolean free_raw_buffer,
                                                const Boolean free_persistent);

• stardata is defined previously (Sec. 8.3.1)
• free_preferences, free_stardata, free_store, free_raw_buffer and free_persistent should be either TRUE or FALSE.

8.3.8 binary_c_free_store_contents

void binary_c_API_function binary_c_free_store_contents(
    struct stardata_t * RESTRICT const stardata
    )

8.3.9 binary_c_free_persistent_data

void binary_c_API_function binary_c_free_persistent_data(
    struct stardata_t * RESTRICT const stardata
    )

8.4 Extension functions

8.4.1 binary_c_version

void binary_c_API_function binary_c_version(struct libbinary_c_stardata_t * RESTRICT const stardata);

• stardata is defined previously (Sec. 8.3.1)

8.4.2 binary_c_list_args

void binary_c_API_function binary_c_list_args(
    struct libbinary_c_stardata_t * RESTRICT const stardata)

• stardata is defined previously (Sec. 8.3.1)

8.4.3 binary_c_show_instant_RLOF

void binary_c_API_function binary_c_show_instant_RLOF(struct libbinary_c_stardata_t * const stardata);

• stardata is defined previously (Sec. 8.3.1)
• Note that binary_c_show_instant_RLOF_period_or_separation is identical to this function (it is kept for old code).

8.4.4 binary_c_initialize_parameters

void binary_c_API_function binary_c_initialize_parameters(struct libbinary_c_stardata_t * RESTRICT const stardata);

• stardata is defined previously (Sec. 8.3.1)

8.4.5 binary_c_help

void binary_c_API_function binary_c_help(struct stardata_t * RESTRICT const stardata,    
                                         char * argstring)

• stardata is defined previously (Sec. 8.3.1).
• argstring is a string provided by the user.

8.4.6 binary_c_events_replace_handler_functions

binary_c_API_function
void  binary_c_events_replace_handler_functions(
    struct stardata_t * const stardata,
    const Event_type type,
    Event_handler_function func(EVENT_HANDLER_ARGS))

• stardata is defined previously (Sec. 8.3.1)
• The event is defined by its type and its handler func. For example, the supernova event handler function looks like this.
  

  Event_handler_function supernova_event_handler(void * const eventp MAYBE_UNUSED,
                                                 struct stardata_t * const stardata,
                                                 void * data MAYBE_UNUSED)
  {
      //struct binary_c_event_t * event = eventp; // you may want this
      ... /* do stuff */
      return NULL;
  }

  
  Please check Sec. 9.12 for more details.

8.4.7 binary_c_generic_event_handler

• eventp is a pointer to the event struct: see Sec. 8.4.6 to retrieve this.
• stardata is defined previously (Sec. 8.3.1)
• data is data passed to the generic handler function.

binary_c_Event_handler_function
binary_c_API_function
binary_c_generic_event_handler(
    void * const eventp MAYBE_UNUSED,
    struct stardata_t * const stardata,
    void * data MAYBE_UNUSED)

8.4.8 binary_c_catch_events

binary_c_API_function
void binary_c_catch_events(struct stardata_t * stardata)

8.4.9 binary_c_erase_events

binary_c_API_function
void binary_c_catch_events(struct stardata_t * stardata)

8.4.10 binary_c_copy_stardata

• The arguments from and to are pointers to allocated stardata structs. from and to should never be identical, otherwise binary_c will raise a BINARY_C_POINTER_FAILURE error.
• copy_previous can be one of the following
  • COPY_STARDATA_PREVIOUS_NONE : do nothing, the new previous_stardatas stack is left NULL
  • COPY_STARDATA_PREVIOUS_COPY : make a copy of history data into a new previous_stardatas stack
  • COPY_STARDATA_MAINTAIN_FROM_STACK_POINTERS : use from's previous_stardatas stack pointers
  • COPY_STARDATA_MAINTAIN_TO_STACK_POINTERS : use to's previous_stardatas stack pointers
• copy_persistent can be one of the following
  • COPY_STARDATA_PERSISTENT_NONE : do nothing, leave persistent data NULL
  • COPY_STARDATA_PERSISTENT_FROM_POINTER : copy from's pointer, i.e. use the existing persistent_data
  • COPY_STARDATA_PERSISTENT_COPY_SHALLOW : make a shallow copy of the persistent_data struct, maintaining any pointers within it as they were
  • COPY_STARDATA_PERSISTENT_COPY_DEEP : make a deep copy of the persistent_data struct (calls copy_persistent() which contains custom code for each item in the persistent_data struct)

binary_c_API_function
struct stardata_t * Returns_nonnull Nonnull_all_arguments
binary_c_copy_stardata(
    const struct stardata_t  * RESTRICT Aligned const from,
    struct stardata_t  * RESTRICT Aligned const to,
    const unsigned int copy_previous,
    const unsigned int copy_persistent
    )

8.4.11 binary_c_check_reject_flags

int binary_c_API_function binary_c_check_reject_flags(
    struct stardata_t * RESTRICT const stardata)

• stardata is defined previously (Sec. 8.3.1)

8.5 API Examples

8.5.1 Arguments and/or the argstring

stardata->star[1].mass = 10.0;
stardata->common.metallicity = 0.02;
stardata->model.max_evolution_time = 15000.0;

8.5.2 Capturing the buffer output

    struct libbinary_c_stardata_t * stardata = NULL;
    struct libbinary_c_store_t * store = NULL;
    struct libbinary_c_persistent_data_t * persistent_data = NULL;

	char * argstring = "binary_c M_1 10 M_2 5 orbital_period 100 eccentricity 0.0 metallicity 0.02";

    binary_c_new_system(&stardata,
                        NULL,
                        NULL,
                        &store,
                        &persistent_data,
                        &argstring,
                        -1);

    /* suppress logging and use internal buffer */
    strcpy(stardata->preferences->log_filename,"/dev/null");
    strcpy(stardata->preferences->api_log_filename_prefix,"/dev/null");
    stardata->preferences->internal_buffering = INTERNAL_BUFFERING_STORE;
    stardata->preferences->batchmode = BATCHMODE_LIBRARY;
    binary_c_evolve_for_dt(stardata,stardata->model.max_evolution_time);  
   
    char * buffer = NULL;
    char * error_buffer = NULL;
    int nbytes = 0;

    /*
     * Get the binary_c output in *buffer and the 
     * error buffer in *error_buffer
     */
    binary_c_buffer_info(stardata,&buffer,&nbytes);
    binary_c_error_buffer(stardata,&error_buffer);

	/* check the error buffer */
    if(error_buffer != NULL)
    {
	     fprintf(stderr,”Error in binary_c : %s\n”,error_buffer);
    }
    else
    {
        /* process the buffer */
     
	

        /* ...... your code goes here ...... */

    }

    /* free used memory */
    binary_c_free_memory(&stardata,TRUE,TRUE,TRUE,TRUE,TRUE);

8.5.3 Memory management and maintaining a store

    struct libbinary_c_stardata_t * stardata = NULL;
    struct libbinary_c_store_t * store = NULL;
    struct libbinary_c_persistent_data_t * persistent_data = NULL;
	
	unsigned int n = 0; // loop until n = 10
	while(n++ < 10)
	{
	   char * argstring;
	   /*... code to define your args ...*/

       binary_c_new_system(&stardata,
                           NULL,
                           NULL,
                           &store,
                           &persistent_data,
                           &argstring,
                           -1);
	   
        binary_c_evolve_for_dt(stardata,stardata->model.max_evolution_time); 

        /* process (buffered) data here or maybe do nothing with it */
		/* ... */

 	   /* free everything except the store */
 	   binary_c_free_memory(&stardata,TRUE,TRUE,FALSE,TRUE,TRUE);  
    }

     /* free the store memory */
     binary_c_free_store_contents(store);
     store = NULL;

   /* ... do your data processing ... */

      binary_c_free_memory(&stardata,TRUE,TRUE,TRUE,TRUE,TRUE);   

      binary_c_free_memory(&stardata,TRUE,TRUE,TRUE,TRUE,TRUE);
      store = NULL;
      stardata = NULL; 

9 Code description and internals

9.1 History

• Learn about how to write C, e.g. https://www.maultech.com/chrislott/resources/cstyle/indhill-cstyle.pdf or https://en.wikipedia.org/wiki/The_C_Programming_Language.
• Learn how to format your C code properly. Section 9.14 describes the required layout.
• Include good comments even if these are “this is a fudge”. Remember that people who do not know how the code works will want to change the code in the future, and I have to check it before it is committed. Descriptions of the physics, paraphrased from a paper if you have to (but remember to give appropriate credit), are encouraged. Lists of input and output variables are required for new functions.
• Include Dprint() statements so that if there is a DEBUG flag set there will be some (useful!) output to the screen during runtime.
• Make sure the names of your variables describe what they do in English. I do not care if the variable names are long (long is good!) and the computer certainly doesn't either.

9.2 How the binary_c code works

9.3 Memory management in binary_c

9.3.1 Memory allocation

9.3.2 Stack size

9.3.3 Main Memory Structures: stardata

stardata_t

The main stardata structure is used to store the information about the stellar system currently being evolved, as well as pointers to all the other memory stores. stardata is set to 0 (the NULL byte '\0') at the beginning of evolution, so everything inside it is either zero (for floats, doubles, ints etc.), or FALSE (for Booleans).

previous_stardata_t

A pointer to the top of the previous_stardata stack. This is used at the end of an evolutionary step to calculate derivatives and perform logging (e.g. change of stellar type).

previous_stardatas

A stack of copies of stardata->n_previous_stardatas previous timesteps' stardata structures.

stardata_stack

A stack of stardata->n_stardata_stack temporary stardata structures used by the various numerical integration schemes (e.g. RK2, RK4). These are generally not final solutions – they are intemediate – and hence should never be touched.

common_t

The common structure stores data that is persistent for this particular stellar system and relates to properties of the system. The space for this structure is inside stardata. This structure should not contain dynamically allocated memory. common is inside stardata so is set to 0 (the NULL byte '\0') at the beginning of evolution, so everything inside it is either zero (for floats, doubles, ints etc.), or FALSE (for Booleans).

model_t

The model structure stores data that is persistent for this particular stellar system and relates to the details of the binary model at a given time. The space for this structure is inside stardata. This structure should not contain dynamically allocated memory. model is inside stardata so is set to 0 (the NULL byte '\0') at the beginning of evolution, so everything inside it is either zero (for floats, doubles, ints etc.), or FALSE (for Booleans).

star_t[NUMBER_OF_STARS]

The information stored to describe each star. NUMBER_OF_STARS of these are in an array inside stardata. This structure should not contain dynamically allocated memory. star[] is inside stardata so is set to 0 (the NULL byte '\0') at the beginning of evolution, so everything inside it is either zero (for floats, doubles, ints etc.), or FALSE (for Booleans).

preferences_t

The preferences structure contains information about how a system should be set up and what physics apply. The location of preferences is saved as a pointer in stardata but its data are not stored in stardata, thus this structure must be allocated and set up separately. This structure should not contain dynamically allocated memory.

store_t

The store structure contains data which is constant, e.g. data tables. Space for the store is allocated on the first run, and it can be kept at the end of the run, so the store only has to be set once (or once per thread). The data in store should be dynamically allocated (e.g. with MALLOC, CALLOC, REALLOC). The store is built in the build_store_contents function, and deleted in the free_store_contents function.

tmpstore_t

The tmpstore contains data which is required to be shared between functions, but is not required to be shared after the current evolutionary timestep is complete. Such data should be dynamically allocated, and each function which uses the tmpstore should check if the appropriate pointer is NULL in which case it should allocated the memory. The free_tmpstore function deletes the data when required. This is usually at the end of stellar evolution, but potentially sooner if many stardata structures are being switched in and out with the API. Data which is required to be persistent between timesteps, which is not constant, and which survives a change in stardata, should be in common. Constant data should be in store.

data_table_t

This stores information describing an interpolation table, including the number of parameters, number of values to be calculated, length of the table and the table data. See the rinterpolate function from librinterpolate.

new_supernova_t

This is a structure that stores information used by the supernova functions.

splitinfo_t

This contains information used by the evolution splitting algorithm.

diffstats_t

This structure is used to compare the state of the stellar system to that of the previous timestep. Changes are then logged.

probability_distribution_t

A generic probability distribution description.

power_law_t

Defines a power law, used in the discs code.

disc_thermal_zone_t

Defines a thermal zone in a disc, used in the discs code.

disc_loss_t

Defines a mass/angular-momentum loss/gain rate, used in the discs code.

disc_t

Defines a disc, used in the discs code.

new_stellar_structure_t

Defines, in a (hopefully) code-independent way, the stellar structure. Used to interface the generic stellar structure algorithm with binary_c .

RLOF_orbit_t

Information on mass loss/transfer/gain during RLOF.

binary_system_t

Defines the binary system for use with the discs code.

kick_system_t

Information used by the (supernova) kick code.

mersenne_twister_data

Used by the random number generator.

binary_c_file

Used by the file access routines, e.g. to store the amount of data written to a file and hence prevent it getting too large.

binary_c_fixed_timestep

Used to make “fixed” timesteps, e.g. so you can output every n million years, exactly (also works in log time).

binary_c_event_t

Used in the events code (see Section 9.12). There are various other custom structures which store data for events (see binary_c_structures.h)

9.3.4 Supplementary data structures

data_table_t

This contains information about a data table. Set up (a pointer to, i.e. data_table_t*) the data table through NewDataTable_from_Array or NewDataTable_from_Pointer. Access the data table through the Interpolate macro (which interfaces with librinterpolate). Delete the table with Delete_data_table. The data_table_t.data pointer points to an array of doubles which contains the data: this memory is not allocated for you. If set up in the store or tmpstore this can be dynamically allocated, elsewhere you have to be careful and probably point to a data array inside stardata.
If you want to set up a data_table_t rather than a data_table_t* you will have to do it manually.

splitinfo_t

This contains information used when EVOLUTION_SPLITTING is defined. See evolution_split.

diffstats_t

Used in constructing the standard log file. See evolution_difflog.

probability_distribution_t

Not sure this is used at present: it defines a probability distribution.

power_law_t

Used to define a power law used by the disc code.

disc_thermal_zone_t

Used to define a thermal zone of a disc in the disc code.

disc_t

Used to define a disc in the disc code.

binary_system_t

Used to define the properties of a binary-star system in the disc code.

9.3.5 Thread safety

$ make libbinary_c.so

• You may not use static variables. Put your data into stardata.
• You may not use global variables (i.e. no extern statements). Put your data into stardata.
• You may not use non-thread-safe C library functions (e.g. strtok and hash functions, use the _r or _s equivalents). Some of these functions have been redefined as macros in binary_c – these macros will deliberately fail the compilation process and hopefully give you a warning.
• You must follow the conventions given above regarding memory allocation in stardata.

9.4 Output

1. Use Printf instead of printf: Printf sends data to buffered_printf. This stores raw output data in a buffer, and outputs either immediately, at the end of evolution, or not at all, depending on what you want to do with the buffer. It is up to you to clear out the buffer after evolution (or on a switch of stardata) with a call to buffer_empty_buffer. You can get the pointer used to store the buffer from buffer_info.
2. binary_c defines a macro printf in binary_c_code_options.h which overrides the default printf and means you can change default printf behaviour.
3. Use _printf to force output to stdout using the C-library's fprintf function.
4. Ensemble output is, if deferred (Sec. 7.4.1), only output once at the end of the grid run. This should be fast, whatever you do, because this only happens once. This can be a lot of data though.
5. warning: experimental If BUFFERED_STACK is defined, you can use binary_c_stack_printf, which is a more advanced buffer with a full stack API (e.g. push and pop functions), that can include (zlib) compression. However, at present this is not used, and may never be a standard part of binary_c .

9.5 Debugging binary_c

• Check the log file, e.g.
  

  $ binary_c log_filename <whatever>

  
  to see what is wrong, and fix it.
• Put in your own
  

  printf

  
  -style statements. Remember to
  

  fflush(stdout);

  
  if you are experiencing segmentation faults to make sure the operating system's buffer is flushed (alternatively, use
  

  $ stdbuf -o0 binary_c ...

  
  to disable buffering).
• Use binary_c 's DEBUG facility to output useful information. See section 9.5.3.
• Use a debugging tool like gdb or valgrind.

9.5.1 General strategy

$ ./binary_c <arguments>

• If you are seeing a segmentation fault, you probably want to now debug with valgrind or gdb.
• If your problem is in your algorithm and is not really a coding error as such, you probably want to use the internal debugging with DEBUG, DEBUG_EXP and Dprint. See Section 9.5.3 below.

9.5.2 Debug builds

$ cd builddir
$ meson setup --reconfigure --buildtype=debug
$ ninja binary_c_install
$ cd ..

9.5.3 DEBUG, Dprint and friends

Dprint(...)

#define DEBUG 1

$ cd builddir
$ meson setup --reconfigure --buildtype=debug
$ ninja binary_c_install

• You can provide an expression which must return true for debugging statements to be output. This is Debug_expression in binary_c_debug.h. E.g. to only have output after 10Myr, use:
  

  #define Debug_expression (stardata->model.time > 10.0)

  
  Again, you will need to do a complete rebuild to make this work.
  By default, Debug_expression is set to 1 so there is output always. This may be a lot of data!
• You can use Dprint_no_newline() macro to prevent the newline after a debugging statement.
• If you want to stop your star at some point, use Debug_stop_expression, e.g. to stop when the mass star 0 is less than $10M_{\odot }$:
  

  #define Debug_stop_expression (stardata->star[0].mass < 10.0)

  
  
• Debugging output lines start with Debug_show_expression, e.g. to output the model number and stellar masses at each timestep,
  

  #define Debug_show_expression " model %d st: %g %g ",   \
          stardata->model.model_number,                   \
          stardata->star[0].mass,                         \
          stardata->star[1].mass

  
  
• You can change the output stream, usually one of stdout or stderr, by changing the macro DEBUG_STREAM.
• You can output file line numbers and filename output with DEBUG_LINENUMBERS and DEBUG_SHOW_FILENAMES.
• If there is an inf or nan in the output, you can force binary_c to stop by defining DEBUG_FAIL_ON_NAN or DEBUG_FAIL_ON_INF. You should define DEBUG_REMOVE_NAN_FROM_FILENAMES so that filenames have “nan” converted to “n_n”, otherwise “remnant” will trigger an exit.

9.5.4 Backtrace

$ meson setup -Dvalgrind=true builddir

9.5.5 Segmentation faults

9.5.6 gdb

$ tbse debug

bt

9.5.7 valgrind and friends

• Note: you may find that some CPU instructions must be disabled because they are not (yet) supported by Valgrind
  10

  e.g. https://bugs.kde.org/show_bug.cgi?id=383010
  . Examples include the avx512 instructions. You can configure the binary_c build for Valgrind with
  

  $ meson setup -Dvalgrind=true builddir

  
  

• memcheck: this is the standard valgrind tool for finding problems with (heap) memory access issues that lead to segmentation faults. Because the memory allocated in binary_c is mostly on the the heap (e.g. stardata is allocated with MALLOC) it is the most useful of valgrind's tools.
  Run this with
  

  $ tbse valgrind

  
  Note that the valgrind options in tbse work for me, but you may need something a bit different, in particular you may need to change the stack size and maximum stack frame.
• massif
  I cannot remember what this does! Run this with
  
  

  $ tbse massif

  
  
• callgrind: a tool to profile code i.e.  determine where time is spent and hence optimize.
  Run this with
  
  

  $ tbse callgrind

  
  
• cachegrind: a tool to analyse cache hits. Run this with
  
  

  $ tbse cachegrind

  
  
• sgcheck: a tool for stack array overrun analyisis.
  Run this with
  
  

  $ tbse sgcheck

  
  
• drd : a tool for thread analysis
  Run this with
  
  

  $ tbse drd

  
  

9.5.8 Thread safety

9.5.9 NaN (not a number) checks

9.6 The binary_c evolution algorithm

• Time is simulated in timesteps of length $\delta t$ (Sec. 9.7).
• Stellar structure is computed at time $t$ using the algorithm of your choice (Section 9.8). This happens in update_system_by_dt().
• During the timestep, derivatives of the system variables are calculated on the assumption that evolution is “smooth”. Variables that change smoothly, e.g. mass or orbital changes changing because of winds or RLOF, are updated for $t+\delta t$ using an integrator.
• If the system changes suddenly as a result of stellar evolution or orbital changes, e.g. common-envelope evolution or a supernova occurs, an event is queued (Section 9.12).
• Checks are performed to make sure $\delta t$ was short enough to resolve smooth changes to the system and that some events, e.g. start of RLOF and supernovae, are resolved as accurately as possible. If not, the timestep is rejected and $\delta t$ is shortened if possible.
• After the “smooth” integration is complete, the events are triggered and the system updated as required.
• A new $\delta t$ is computed (Sec. 9.7) and evolution continues until both stars are massless, or the maximum time or maximum model number is reached.

9.7 Timestep calculation

#define DT_LIMIT_TIDES 44

#define ___LOGGING

9.7.1 Fixed timesteps / timestep triggers

#define FIXED_TIMESTEP_YIELDS 0
#define FIXED_TIMESTEP_MEGAYEAR 1 
#define NUMBER_OF_FIXED_TIMESTEPS 2 

t = &stardata->model.fixed_timesteps[FIXED_TIMESTEP_MEGAYEAR]; 
t->enabled = TRUE; // enable it
t->begin = 10.0; // start at 10Myr
t->end = stardata->model.max_evolution_time; // end at the end of evolution
t->step = 1.0; // step is 1Myr
t->next = t->begin + t->step; // next should be at the start + 1 Myr
t->logarithmic = FALSE; // do not use logarithmic times
t->final = TRUE; // do log on the final timestep
t->previous_trigger = t->previous_test = t->begin; // set trigger

const Boolean triggered = timestep_fixed_trigger(stardata,
                                                 FIXED_TIMESTEP_MEGAYEAR);

if(triggered == TRUE)
{
	/* output stuff */
}

9.8 Stellar structure computation in binary_c

STELLAR_STRUCTURE_ALGORITHM_MODIFIED_BSE

binary_c 's version of BSE (default)

STELLAR_STRUCTURE_ALGORITHM_NONE

Do nothing!

STELLAR_STRUCTURE_ALGORITHM_EXTERNAL_FUNCTION

Use an external function (might be handy if MESA ever sorts out an API?), see Section 9.13.2 for details.

STELLAR_STRUCTURE_ALGORITHM_MINT

The next-generation MINT library (work in development).

9.9 Derivatives in binary_c

• stardata->star[k].derivative[n] where k is the star number and n is the derivative number. These are defined in STELLAR_DERIVATIVES_LIST in binary_c_derivatives.def.
• stardata->model.derivative[n] where n is the derivative number. These are defined in SYSTEM_DERIVATIVES_LIST in binary_c_derivatives.def.

• Set stardata->preferences->derivative_logging to True
• Call
  

  show_derivatives(stardata);

  
  

9.10 Time integration

9.11 Timestep rejection

CANNOT_SHORTEN_RESTORE_AND_TRY_EVENTS

This restores the previous stardata, hence the masses and orbital variables, but still tries to run any events (such as stellar merging) that were triggered. This is, at the time of writing, the default.

CANNOT_SHORTEN_CONTINUE

This just carries on with a short timestep, ignoring the numerical problems. Variables that fail their check function are not updated, so will be out of date, however they will be (at least) physical (e.g. not a negative mass).

CANNOT_SHORTEN_FAIL

This causes an error to be triggered and evolution halted. If you are being careful, you probably want to do this.

9.12 Events

9.12.1 Queueing an event on the event stack

• stardata: the usual pointer to a stardata struct
• event_type: an integer identifying the event type. There are defined in events_macros.h
• event_handler_function: this is a pointer to a function to be called when the event is triggered. This is required to be non-NULL.
• erase_event_handler_function: this is a pointer to a function to be called when the event is erased. Ignored if NULL.
• event_data: this is a void* pointer, i.e. it is of whatever type you want it to be (your handler function should know), to data to be sent to the handler function. This can be NULL.
• unique: a Boolean specifying whether this event is one of a kind, or not. For example there can only be one common envelope per timestep, so
  

  unique==TRUE

  
  , but there could be more than one supernova, so
  

  unique==FALSE

  
  .

        struct binary_c_new_common_envelope_event_t * event_data =
            Malloc(sizeof(struct binary_c_new_common_envelope_event_t)); 

        if(Add_new_event(stardata,
                         BINARY_C_EVENT_COMMON_ENVELOPE,
                         &common_envelope_event_handler,
                         NULL,
                         event_data,
                         UNIQUE_EVENT) == BINARY_C_EVENT_DENIED)
        {
            Dprint("not allowed an event :(\n");
            Safe_free(event_data);
        }
        else
        {
            event_data->donor = donor;
            event_data->accretor = accretor;
            Dprint("added event!\n");
        }

9.12.2 Testing the event stack

• Call the events_pending function to return TRUE if there are events pending, FALSE otherwise.
  

  const Boolean x = events_pending(stardata);

  
  
• Call events_pending_of_type to return TRUE if there are events of a given type pending, FALSE otherwise.
  

  const Boolean y = events_pending_of_type(stardata,BINARY_C_EVENT_COMMON_ENVELOPE);

  
  
• Call event_stack_string to return a char* string describing the stack, suitable for logging and/or debugging. You need to Safe_free() the string.
  

  char * evstring = event_stack_string(stardata);
  printf(“Event stack: %s\n”,evstring);
  Safe_free(evstring);

  
  

9.12.3 Erase the stack

erase_events(stardata);

erase_events_of_type(stardata,type,except);

erase_event(stardata,&event);

9.12.4 Catch events

9.12.5 Event handler functions

Event_handler_function common_envelope_event_handler(void * eventp,
                                                     struct stardata_t * stardata,
                                                     void * data)
{
	/* a pointer to the event */
    struct binary_c_event_t * const event = eventp;
    
	/* a pointer to the event data */
    struct binary_c_new_common_envelope_event_t * const event_data =
        (struct binary_c_new_common_envelope_event_t*) data;

	/* information stored in the event data */
    struct star_t * const donor = event_data->donor;
    struct star_t * const accretor = event_data->accretor;

	/* ... now do stuff with donor and accretor ... */

9.12.6 Events through the API

binary_c_catch_events

This calls catch_events()

binary_c_events_replace_handler_functions

This allows you to replace a handler function on a particular event type with your own handler function.

binary_c_generic_event_handler

This calls generic_event_handler() which in turn calls the event handler that binary_c would use. This is useful if you are catching an event yourself but in addition want binary_c to do what it normally does.

binary_c_erase_events

This calls erase_events()

9.13 Function hooks

9.13.1 Standard hooks

Call_function_hook(extra_update_binary_star_variables);

BINARY_C_HOOK_catch_events

alternative function to catch events, e.g. to do event logging.

BINARY_C_HOOK_custom_output

called after a timestep to do extra logging.

BINARY_C_HOOK_extra_apply_derivatives

called by the solver to compute more derivatives.

BINARY_C_HOOK_extra_calculate_derivatives

called during time evolution to compute more derivatives.

BINARY_C_HOOK_extra_ensemble

called in the ensemble_log to do extra ensemble calculations.

BINARY_C_HOOK_extra_update_binary_star_variables

called to compute further binary-star variables.

BINARY_C_HOOK_post_time_evolution

called just after time evolution of the system has been done, but before rejection is tested.

BINARY_C_HOOK_pre_time_evolution

called at the start of each timestep just before time evolution begins.

9.13.2 Extra, non-standard function hooks

stellar_structure_hook

used when a custom stellar structure algorithm is set (see Sec. 9.8). This function takes a caller id number and a variable number of arguments.

int (*stellar_structure_hook)(const Caller_id caller_id,
                              ...);

extra_stellar_evolution_hook

this is a function that computes extra stellar evolution after update_system_by_dt() does its work.

void (*extra_stellar_evolution_hook)(struct stardata_t * stardata,
                                     const Evolution_system_type system_type);

extra_update_binary_star_hook

this is a function that computes extra binary evolution after update_system_by_dt() does its work.

void (*custom_supernova_kick_hook)(struct stardata_t * const stardata,
                                   struct stardata_t * const pre_explosion_stardata,
                                   struct star_t * const star,
                                   struct star_t * const pre_explosion_star);

9.14 Code layout, header files, flow

9.14.1 API

9.14.2 batchmode

9.14.3 binary_star_functions

9.14.4 buffering

INTERNAL_BUFFERING_OFF

Output to stdout (no buffer is stored).

INTERNAL_BUFFERING_PRINT

Store in the buffer and dump the buffer's contents to stdout at the end of each timestep.

INTERNAL_BUFFERING_STORE

Store in the buffer for later use (this is probably what you want if you are using the API).

9.14.5 common_envelope

9.14.6 debug

9.14.7 disc

9.14.8 envelope_intgeration

9.14.9 equation_of_state

9.14.10 events

9.14.11 evolution

• evolve_system_binary_c is the main time loop which sets up the system at its initiation, loops over time (at each timestep calling evolution, see below) and then cleans up when things are all finished.
• evolution The main time-evolution function. This calls the appropriate integration scheme to further the binary system under investigation in time. The default scheme is forward-Euler, but Runge-Kutta 2nd and 4th order are also available. The function evolution_step in turn, for all the schemes, calls the other parts of binary_c that do all the appropriate physics.

9.14.12 file

9.14.13 galactic

9.14.14 libmemoize

9.14.15 librinterpolate

9.14.16 logging

• log_every_timestep which is called every (successful) timestep to output the current state of the star. This is where you want to put your logging code! Please remember: when logging use the Printf macro, not C's printf-type function calls.

9.14.17 maths

• Some of the code is experimental so probably not used.
• Anything you put in this directory must be free and freely distributable software. There are no routines from Numerical Recipes in C because these are not free software.

9.14.18 memory

9.14.19 misc

9.14.20 nucsyn

9.14.21 opacity

9.14.22 orbit

9.14.23 perl

9.14.24 python

9.14.25 RLOF

9.14.26 setup

9.14.27 signals

9.14.28 single_star_functions

9.14.29 spectra

9.14.30 stellar_colours

9.14.31 stellar_structure

9.14.32 stellar_timescales

9.14.33 string

9.14.34 supernovae

9.14.35 tables

9.14.36 timers

9.14.37 timestep

9.14.38 triple_star_functions

9.14.39 wind

9.14.40 zfuncs

9.15 nucsyn

#define NUCSYN

#ifdef NUCSYN
...
#endif /* NUCSYN */

9.15.1 Header files and isotope arrays

X[0]=0.5;

#define XC12 2

X[XC12]=0.5;
/* or, similarly */
N[XC12]=1e-8;

9.15.2 Setup functions

9.15.3 First and Second Dredge-up

9.15.4 TPAGB functions (3rd dredge-up and HBB)

num_thermal_pulses < 0

9.15.5 Hot-Bottom Burning

1. The original analytic routine. This uses analytic solutions to the CN, ON, NeNa and MgAl cycles, together with some approximate fudges to join them into the CNO and NeNaMgAl cycles, to solve for the abundances. This is fast but sometimes, when used outside the range of the approximations, very unstable.
2. The new numerical solver. This uses a 4th-order implict (Kaps-Rentrop) scheme to solve for the abundances as a function of time. It does not depend on approximations, and currently burns the $pp$-chain, CNO cycles (hot or cold) and the full NeNa/MgAl chains/cycles. In theory it can be extended to any nuclear network (although it is designed for small networks – it will get very slow with larger networks). It turns out that, after much code optimization, the numerical solver is about as fast as the analytic solver! I think this is because to solve numerically requires additions, subtractions, multiplications and divisions, while analytic solutions require lots of exponentials. However, whether the numerical solver quickly converges on a result depends on the initial timestep. Be careful with that, I have a number of schemes which can improve this.

9.15.6 nucsyn_WR

9.15.7 The $r$-process

9.15.8 Winds and Mixing

9.15.9 Explosions (supernovae and novae)

9.15.10 Yield calculations

9.15.11 Logging and minor functions

9.15.12 Other stellar remnants

Xsurf[Xn]=1.0;

9.16 Coding style

• We require that the compiler supports C11 constructs with GNU extensions. This means GCC 4.9 or later. Our standard is equivalent to the GCC compiler flag c_std=gnu11.
• The binary_c style is based on the Allman style with a few minor changes.
  • This means for and while loops are like this
    

    for(i=0; i<10; i++)
    {
        ...
    }

    
    
  • If statements are like this
    

    if(x == TRUE)
    {
        ...
    }

    
    please be explicit: do not just use
    

    if(x)

    
    except in testing. Please use spaces around operators, so
    

    if(x == TRUE) // good
    if(x==TRUE) // bad

    
    
  • Note that there is no space after the constructor (for, if, …).
    

    for (i=0; i<10; i++) // wrong!
    {
        ...
    }

    
    
  • Try to keep lines short, shorter than 80 characters if possible.
    

    /* this is good */
    printf("got nstrings = %ld : %s, %s, %s...\n",
           nstrings,
           nstrings >= 1 ? strings[0] : "",
           nstrings >= 2 ? strings[1] : "",
           nstrings >= 3 ? strings[2] : "");
    /* this is bad */
    printf("got nstrings = %ld : %s, %s, %s...\n",nstrings,nstrings >= 1 ? strings[0] : "",nstrings >= 2 ? strings[1] : "",nstrings >= 3 ? strings[2] : "");

    
    
  • All warnings from the compiler are considered to be bugs. We build with -Wpedantic for a reason.
• Indent with four spaces (emacs indents C like this automatically)
  

  {
   bad
    bad
     bad
      good
  }

  
  
• Comments should be multi-lined for enhanced legibility
  

  /*
   * This is a good comment
   */
  
  /* This is an ugly comment, ok for temporary work */
  
  // This is a bad comment

  
  the exception is after
  

  #endif

  
  e.g.,
  

  #endif // This is a good comment

  
  

9.16.1 Macros

• Macros used as flags should use CAPTIALS and, when used in #ifdef … #endif pairs, you should include a comment at the end of the pair to say specify the opening macro, for example.
  

  #define FLAG_MACRO
  
  
  #ifdef FLAG_MACRO
  
  ... do stuff 
  
  #endif // FLAG_MACRO

  
  
• Constant macros should use upper case, e.g.,
  

  #define CONSTANT_MACRO 3

  
  
• Function macros should be named with the first character in upper case, the rest in lower case, and when you address arguments remember to wrap them in parentheses, e.g.,
  

  #define Pow2(X) ((X)*(X))
  #define Other_star(K) ((K)==0 ? 1 : 0) 

  
  exceptions to this are the macros used for stellar types, PRINTF which is just mapped to Printf for backward compatibility, and macros such as likley and unlikley which are kept in lower case to match external code (in this case the Linux kernel).
  Most function macros are in binary_c_function_macros.h.
• You should NOT use X as a function macro name. binary_c uses X-macros
  13

  https://en.wikipedia.org/wiki/X_Macro
  , so requires X to be free for those, not for your work. If you do use X as a function macro, expect it to be destroyed randomly.
• Macros which are used only locally, and variables used in macro expressions, should be prefixed with two underscores, as is standard in C.
  

  #define __LOCAL_MACRO 1

  
  
• When comparing to TRUE and FALSE, please be explicit, i.e. 
  

  == TRUE

  
  or
  

  == FALSE

  
  , e.g.,
  

  if(vb == TRUE)
  {
      /* ... do something ... */
  }

  
  
• You are free to use GCC's statement expressions (https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html) but please prefix them with
  

  __extension__

  
  and wrap them in
  

  #ifdef USE_GCC_EXTENSIONS
       ... /* the macro you want to use */
  #else
       ... /* fallback code */
  #endif // USE_GCC_EXTENSIONS

  
  The macro USE_GCC_EXTENSIONS may, or may not, be defined, depending on your compiler. With a modern GCC or Clang, it is, but please do not rely on this.
  Note that some software used by binary_c now requires GCC extensions, such as libcdict.
• Please use a macro that calls a macro should you require a temporary variable. In the example below, Max(A,B) is the macro that the use calls. This then calls another implementation macro passing, along with A and B, a unique LABEL string and the COUNTER (usually __COUNTER__ as provided by the compiler) which is a unique number. The implementation macro then does the work, constructing unique variable names from LABEL and COUNTER using __typeof__.
• 
  

  /*
   * this macro does the work but calculates (A) twice, so might
   * be inefficient if (A) is a function call.
   */
  #define Max_macro(A,B) ((A)>(B) ? (A) : (B))
  
  #ifdef USE_GCC_EXTENSIONS
  /*
   * An implementation statement expression that sets (A)
   * and (B) into temporary variabless so they are calculated 
   * only once.
   */
  #define Max_implementation(A,B,LABEL,COUNTER)           \
      __extension__                                       \
      ({                                                  \
          __typeof__(A) Concat3(__a,LABEL,COUNTER) = (A); \
          __typeof__(B) Concat3(__b,LABEL,COUNTER) = (B); \
          Max_macro(Concat3(__a,LABEL,COUNTER),           \
                    Concat3(__b,LABEL,COUNTER));          \
      })
  /*
   * The macro called by the user, sends the unique string “Max”
   * and __COUNTER__ to the implementation along with (unevaluated,
   * at this stage) A and B.
   */
  #define Max(A,B) Max_implementation((A),(B),Max,__COUNTER__)
  
  #else
  /* 
   * Fallback if GCC extensions are not available.
   */
  #define Max(A,B) Max_macro((A),(B)) 
  
  #endif // USE_GCC_EXTENSIONS
  

  
  

9.17 Directory structure

• The src directory, which holds all the .c, .h and .def files which are the source code of binary_c.
• doc contains documentation.
• src/perl contains some useful Perl scripts.
• src/python contains Python scripts. These are mostly designed to work with $binary\_c-python$ and include the ensemble manager.
• src/inlists contains inlists for the ensemble manager.
• unit_tests contains unit testing components.
• meson contains scripts used by Meson during configuration.
• builddir contains the Meson/Ninja build information. You can delete this at any time, but you will have to rebuild everything from scratch if you do.
• triple contains triple-star extensions (work in progress).
• apitest contains API testing code.

9.18 Control scripts

10 Advanced Configuration

10.1 Meson configuation

10.2 binary_c-config

$ binary_c-config help

--cflags        Show the flags which were used to build binary_c (same as --flags)
--libs          Show library linking information
--libs_list     Show library linking information as a space-separated list without -l
--help          Show this help and exit
--version       Show binary_c's version number.
--full_version  Show binary_c's full version string.
--cc            Show the C compiler used to build binary_c
--cc_version    Show the version of the C compiler used to build binary_c
--ld            Show the linker used to build binary_c
--ldd           Show binary_c's dependencies
--incdirs       Show binary_c's include dirs (for header files)
--incdirs_list  Show binary_c's include dirs (for header files) as a space-separated list without -I
--libdirs       Show binary_c's library search directories during build
--libdirs_list  Show binary_c's library search directories during build as a space separated list without -L
--git_url       Show the URL of binary_c's git source (if available)
--git_branch    Show the git branch being used (if available)
--git_revision  Show the revision of binary_c's git source (if available)
--structs       Show structure sizes
--svn_url       Show the URL of binary_c's svn source (if available)
--svn_revision  Show the revision of binary_c's svn source (if available)
--build_date    Show the date and time of binary_c's build
--define_macros Show macros defined by -D... in the compiler flags (except -D__whatever__)
--undef_macros  Show macros undefined by -U... in the compiler flags (except -U__whatever__)
--all_define_macros Show macros defined by -D... in the compiler flags
--all_undef_macros  Show macros undefined by -U... in the compiler flags
--defaults      Show binary_c's default settings
--defaults_set  Show the label of the current defaults set 
--tests         Show the results of unit testing.

$ binary_c-config define_macros
-DOPERATING_SYSTEM=linux -DLINUX -DPOSIX -DLARGEFILE_SOURCE -DALIGNSIZE=8  -DCPUFREQ=4800 -DBINARY_C_SRC=/home/izzard/git/binary_c/src -DBINUTILS_VERSION=2.38 -DBFD_2_33 -D_FILE_OFFSET_BITS=64      -DFPU_CONTROL                -DGIT_REVISION=6624:20230119:c5d02fd9c -DGIT_URL=git@gitlab.com:binary_c/binary_c.git -DGIT_BRANCH=master

$ ./binary_c-config git_url
git@gitlab.com:binary_c/binary_c.git

$ binary_c-config version
2.2.3

$ ./binary_c-config git_revision
"6624:20230119:c5d02fd9c"

$ binary_c-config cflags
-std=gnu18 -DOPERATING_SYSTEM=linux -DLINUX -DPOSIX -DLARGEFILE_SOURCE -DALIGNSIZE=8 -fstrict-aliasing -Wstrict-aliasing -g -Wno-sizeof-pointer-div -Wpedantic -Wshadow -Wno-variadic-macros -fstack-protector-all -rdynamic -fsignaling-nans -march=native -mtune=native -frounding-math -fno-stack-protector -ffloat-store -D__ACCURATE_BINARY_C__ -fno-finite-math-only -fasynchronous-unwind-tables -fvisibility=hidden -export-dynamic -O0 -DCPUFREQ=4800 -DBINARY_C_SRC=/home/izzard/git/binary_c/src -DBINUTILS_VERSION=2.38 -DBFD_2_33 -D_FILE_OFFSET_BITS=64 -D__HAVE_LINK_H -D__HAVE__VA_OPT__ -D__HAVE_GNU_QSORT_R -D__HAVE_NATIVE_EXP10 -D__HAVE_POSIX_FADVISE -DFPU_CONTROL -D__HAVE_ATTRIBUTE___RESTRICT____ -D__HAVE_ATTRIBUTE_ALLOC_SIZE__ -D__HAVE_ATTRIBUTE_AUTO_TYPE__ -D__HAVE_ATTRIBUTE_BUILTIN_EXPECT__ -D__HAVE_ATTRIBUTE_CONST__ -D__HAVE_ATTRIBUTE_DEPRECATED__ -D__HAVE_ATTRIBUTE_GNU_PRINTF__ -D__HAVE_ATTRIBUTE_HOT__ -D__HAVE_ATTRIBUTE_PACKED__ -D__HAVE_ATTRIBUTE_PURE__ -D__HAVE_ATTRIBUTE_MALLOC__ -D__HAVE_ATTRIBUTE_NONNULL__ -D__HAVE_ATTRIBUTE_NORETURN__ -D__HAVE_ATTRIBUTE_RETURNS_NONNULL__ -D__HAVE_ATTRIBUTE_UNUSED__ -DGIT_REVISION=6624:20230119:c5d02fd9c -DGIT_URL=git@gitlab.com:binary_c/binary_c.git -DGIT_BRANCH=master -D__HAVE_LIBC__ -D__HAVE_LIBCFITSIO__ -D__HAVE_LIBGSL__ -I/home/izzard/include -D__HAVE_LIBGSLCBLAS__ -D__HAVE_LIBDL__ -D__HAVE_LIBPTHREAD__ -D__HAVE_LIBUUID__ -D__HAVE_LIBZ__ -D__HAVE_LIBBFD__ -D__HAVE_LIBBSD__ -D__HAVE_LIBIBERTY__ -D__HAVE_LIBJEMALLOC__ -D__HAVE_LIBM__ -D__HAVE_LIBMEMOIZE__ -D__HAVE_LIBRINTERPOLATE__ -D__HAVE_LIBCDICT__ -D__HAVE_LIBUNWIND__ -D__HAVE_LIBBACKTRACE__ -D__HAVE_BACKTRACE_H__ -D__HAVE_IEEE754_H__ -D__HAVE_DRAND48__ -D__HAVE_HSEARCH_DATA__ -D__HAVE_MALLOC_H__ -D__HAVE_SETITIMER__ -D__HAVE_HAS_INCLUDE -D__HAVE_PKG_CONFIG__ -D__HAVE_VALGRIND__ -D__SHOW_STARDATA__ -D__DIFF_STARDATA__ -D__HAVE_LIBIBERTY_LIBIBERTYH__ -D__HAVE_BZCAT__ -D__HAVE_ZCAT__ -D__HAVE_7Z__ -O0

10.3 meson -D…

• LINUX is defined if you're running Linux. This is useful for some timers and segfault catchers which only work with the Linux libraries.
• LARGEFILE_SOURCE and FILE_OFFSET_BITS were once useful for large output files on 64-bit machines (>2GB). This may no longer be a problem but they do not hurt.
• CPUFREQ is the frequency of your CPU (in Mhz) – this is very useful for timing information. (Taken from /proc/cpuinfo if available, sysctl -a on MacOSX.)
• GIT_REVISION and GIT_URL provide binary_c with information about the version of the code you are using. This can prove essential when debugging. See section 12.17 for more details.

10.4 binary_c_code_options.h

• SEGFAULTS This should be set if want segfaults on a code failure. This is useful if you are debugging with gdb.
• ACML should be set if you wish to use the AMD math (sic) library. Note: this has not been tested for a long time.
• DUMA should be set if you wish to use the DUMA memory checking library. Note: this has not been tested for a long time.
• BATCHMODE Enables the interactive batch mode. This is required by some legacy codes.
• TIMEOUT_SECONDS Every time the code is run, a timer is set. If this is not reset within TIMEOUT_SECONDS seconds, binary_c is deliberately crashed. Clearly, if your star has not evolved in 60 seconds then something is wrong. By default this is zero, so is ignored.
• TIMEOUT_SECONDS_WITH_VALGRIND is like TIMEOUT_SECONDS but used when running Valgrind which requires often a lot more time.
• ALLOC_CHECKS This should be defined, it enables checks on memory allocation (which slows the code down a little bit). Note that if DEBUG is $1$ this will be set automatically.
• STARDATA_STATUS used to allow output from the stardata_status function.
• Restrict, Fastcall, Constant_function, MAYBE_UNUSED and Pure_function are used to tell the compiler if a function can use restricted memory access, should use fastcall (something to do with registers?), is a constant function, may be an unused variable or function, or is a pure function. See the gcc manual for details, or just leave them.
• MILLISECOND_RANDOMNESS Improves the resolution of the random number seed. You probably want this.
• NANCHECKS enables checks in many parts of the code for NaN (Not A Number). While this is slow it is very useful for catching bugs.
• RANDOM_SYSTEMS is used in conjunction with --repeat to run randomly chosen systems to check for bugs. I suggest you use the random_systems.pl script to generate random binaries.

10.5 binary_c_parameters.h

//#define MINT

10.6 nucsyn/nucsyn_parameters.h

• Enable NUCSYN_FIRST_DREDGE_UP to make first dredge-up happen on the GB.
  
  • You want this, and probably you want to enable NUCSYN_FIRST_DREDGE_UP_AMANDAS_TABLE and NUCSYN_FIRST_DREDGE_UP_ACCRETION_CORRECTION. These enable tabular lookups of the abundance changes (better than fitting formulae) and a simple prescription to deal with abundance changes due to accretion.
  • NUCSYN_FIRST_DREDGE_UP_ACCRETION_CORRECTION_FROM_TAMS is similar but bases changes on the terminal-age main sequence abundances – this is better in the case of accretion of e.g. carbon (i.e. for CEMPs).
  • NUCSYN_FIRST_DREDGE_UP_PHASE_IN enables a phased change of the abundance to better match detailed models (the default model assumes that 1st DUP happens instantaneously).
  • NUCSYN_FIRST_DREDGE_UP_RICHARDS_TABLE should be enabled in addition to NUCSYN_FIRST_DREDGE_UP_AMANDAS_TABLE to use Richard Stancliffe's models in place of Amanda's when in the appropriate mass/metallicity range (down to $Z=10^{-5}$ while Amanda's are valid only down to $10^{-4}$).
• Enable NUCSYN_SECOND_DREDGE_UP to make second dredge-up happen at the beginning of the TPAGB. You want this.
• Enable NUCSYN_THIRD_DREDGE_UP to make third dredge-up happen during the TPAGB.
  
  • You probably also want NUCSYN_THIRD_DREDGE_UP_AMANDA to get the intershell abundances from a table based on Amanda's models.
  • You can choose whether to get these numbers from either the old data USE_TABULAR_INTERSHELL_ABUNDANCES_KARAKAS_2002 (no s-process; use only for testing!) or the new table USE_TABULAR_INTERSHELL_ABUNDANCES_KARAKAS_2012 (with s-process, deprecates the Busso/Gallino tables which have been removed).
  • MINIMUM_ENVELOPE_MASS_FOR_THIRD_DREDGEUP is the minimum mass for third dredge up, set on the command line with --minimum_envelope_mass_for_third_dredgeup or MINIMUM_ENVELOPE_MASS_FOR_THIRD_DREDGEUP_DEFAULT by default ($0.5M_{\odot }$ based on Straniero's models).
  • You have the option of defining NUCSYN_THIRD_DREDGE_UP_RICHARD instead, which uses Richard's intershell material (but is less complete than Amanda's tables).
  • NUCSYN_THIRD_DREDGE_UP_TABULAR_NCAL should be used for tabular fits to the NCAL parameter instead of the old (dodgy?) formula fit.
  • NUCSYN_THIRD_DREDGE_UP_HYDROGEN_SHELL activates the algorithm which takes into account dredge up of the hydrogen-burning shell at low metallicity. At high metallicity it is negligible. You should activate this.
  • NUCSYN_THIRD_DREDGE_UP_MULTIPLIERS allows command-line modification of the amount of material dredge up. It does not hurt to define this if you do not use it.
  • USE_TABULAR_INTERSHELL_ABUNDANCES forces the use of tables instead of fits to the intershell abundances: this is probably what you want (there are checks for going off the end of the tables).
• Enable PADOVA_MC1TP to use the Padova group's $M_c^{1TP}$ rather than the Karakas et al. (2002) fits (only for $M<3M_{\odot }$, above $3M_{\odot }$ the difference is small anyway).
• Enable NUCSYN_TPAGB if you want to use nucleosynthesis on the TPAGB (e.g. third dredge-up and HBB).
• You can control the luminosity behaviour on the TPAGB with NUCSYN_TPAGB_LUMTYPE. If zero then an average luminosity is used, if 1 then post-flash dips are included for the first NUCSYN_PULSE_LUM_DROP_N_PULSES dips (DTFAC must be set to something small e.g. 0.1 to resolve the dips). The drop is by a factor THERMAL_PULSE_LUM_DROP_FACTOR and the luminosity rises again on a timescale 1/THERMAL_PULSE_LUM_DROP_TIMESCALE of the interpulse period. The spiky_luminosity variable in each star structure follows the luminosity changes. It is impossible to put the changes in the luminosity itself because the timestep becomes very small when the luminosity (and so radius) changes suddenly._
• NUCSYN_SMOOTH_AGB_RADIUS_TRANSITION smooths the transition between Hurley and Karakas $L$ and $R$: it's a bit of a fudge (uses NUCSYN_SMOOTH_AGB_RADIUS_TRANSITION_SMOOTHING_TIME).
• NUCSYN_TPAGB_MIN_LUMINOSITY is a minimum luminosity for TPAGB stars, a bit of a fudge, usually $100L_{\odot }$.
• MAX_TPAGB_TIME the maximum time (in years) for which the TPAGB phase is allowed to run, just in case something goes wrong, default is $10^{8}years$.
• NUCSYN_ROBS_REFITTED_TPAGB_INTERPULSES enables updated fits for the interpulse period.
• MINIMUM_INTERPULSE_PERIOD is the minimum interpulse period, default $10^{-4}years$
• Enable NUCSYN_TPAGB_HBB if you want to HBB on the TPAGB. Choose either the analytic burning method, NUCSYN_ANAL_BURN, or the numerical solver NUCSYN_NUMERICAL_BURN. The latter has proved to be reliable, and more flexible, so I would go with that.
  
  • If you choose NUCSYN_ANAL_BURN you can specify which nuclear reactions to include: NUCSYN_TPAGB_HBB_CN_CYCLE and NUCSYN_TPAGB_HBB_ON_CYCLE are the CN and ON parts of the CNO cycling in HBB, NUCSYN_TPAGB_HBB_NeNa_CYCLE activates the approximate NeNa cycling, NUCSYN_TPAGB_HBB_MgAl_CYCLE activates the approximate MgAl cycling. Enable NUCSYN_CNO_ASSUME_STABLE to assume solutions of the CNO quadratic are always real (i.e. a stable solution, neglect the oscillating parts), NUCSYN_NENA_LEAK will allow leakage from NeNa to MgAl (do this), NUCSYN_Na22_EQUILIBRIUM will force Na22 into equilibrium (otherwise it is not calculated because it is unstable and you probably do not care), NUCSYN_Al26m follows the metastable state of ${}^{26}Al$ (again, do you care? it makes little difference except at low $Z$) and NUCSYN_MGAL_LEAKBACK allows the ${}^{27}Al(p,\alpha {)}^{24}Mg$ reaction, which should be negligible.
  • If you choose NUCSYN_NUMERICAL_BURN then most of the above options are automatically taken into account by the burning schemes. However, you can choose your schemes with NUCSYN_NETWORK_PP ($pp$-chain), NUCSYN_NETWORK_COLDCNO (cold CNO cycle, which is sufficient for temperatures less than ${log}_{10}T/K\lesssim 8.2$), NUCSYN_NETWORK_HOTCNO (hot CNO cycle, explicitly includes $\beta$ decays and is probably not necessary for most purposes) and NUCSYN_NETWORK_NeNaMgAl (NeNa and MgAl cycles/chains).
    NUCSYN_NORMALIZE_NUCLEONS preserves the number of nucleons in the burning routine, which should prevent numerical errors.
• Further, NUCSYN_HBB_RENORMALIZE_MASS_FRACTIONS will renormalize the total mass fraction to one in order to remove some errors.
• NUCSYN_S_PROCESS activates the elemental $s$-process, you might well want this.
• Enable NUCSYN_STPAGB for STPAGB stars. There are many associated options which you should not play with.
• The NUCSYN_HS_LS_LOG is an option for s-process logging and outputs the value of $\left[hs\right]$, $\left[ls\right]$ and $\left[hs/ls\right]$ (see e.g. Gallino et al., 1998).
• NUCSYN_RADIOACTIVE_DECAY allows decay of isotopes.
• NUCSYN_FORCE_DUP_IN_COMENV forces dredge up when a common envelope forms. This seems likely, as a companion star spiralling in will mix up the envelope.
• NUCSYN_WR switches on the massive star (and WR/Helium star) code. NUCSYN_WR_METALLICITY_CORRECTIONS switches on the $Z\ne 0.02$ extension to this code. NUCSYN_WR_LOG outputs some information during the O/B or WR phase. NUCSYN_WR_TABLES uses tabular values instead of fits (please use this) and NUCSYN_WR_RS_TABLE enables Richard Stancliffe's tables (this code is in testing).
• NUCSYN_NOVAE and NUCSYN_SUPERNOVAE switch on the novae and supernovae respectively. You should enable NUCSYN_NOVAE_FROM_TABLES to use tables instead of fits.
• For core-collapse supernovae choose either NUCSYN_CCSNE_WOOSLEY_WEAVER_1995 or NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004.
  
  • In the case of NUCSYN_CCSNE_WOOSLEY_WEAVER_1995 you can choose to use their NUCSYN_SUPERNOVAE_CC_WW95_A or B or C models.
  • In the case of NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004 you can either use their yields directly (best to do this as then the yields really are a function of mass cut) or use the Portinari-corrected versions which are less accurate (NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004_PORTINARI). Define NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004_EXTRAPOLATE to extrapolate beyond the end of their table at the high metallicity ($Z>0.02$) end.
  • NUCSYN_SN_REDUCE_SODIUM reduces the sodium yield: avoid this.
  • NUCSYN_LIMIT_SN_TYPES allows you to exclude SN yields from various types on the command line
  • NUCSYN_R_PROCESS allows $r$-process yields: choose from NUCSYN_R_PROCESS_ARLANDINI1999 or NUCSYN_R_PROCESS_SIMMERER2004. You also need to choose NUCSYN_R_PROCESS_FROM_SNE_MASS which is the mass of $r$-process material ejected in the SN, typically I choose $10^{-6}{M}_{\odot }$ but this is quite arbitrary.
• NUCLEAR_REACTION_RATE_MULTIPLIERS allows you to change nuclear reaction rates on the command line (see Izzard et al., 2007 for the reasoning).
• NUCSYN_SIGMAV_PRE_INTERPOLATE allows interpolation of the nuclear cross section $⟨\sigma v⟩$ from a pre-calculated table, rather than a recalculation of the values from analytic formulae as a function of temperature. This is about $10\%$ quicker. You can change the resolution in $T_9=T/10^{9}K$ with NUCSYN_SIGMAV_INTERPOLATION_RESOLUTION and you should enable NUCSYN_SIGMAV_INTERPOLATE_LOGT9 and NUCSYN_SIGMAV_INTERPOLATE_LOGSIGMAV so the interpolations are done in log space. SIGMAV_TINY ($10^{-100}$) is a minimum value for the cross section. Enable NUCSYN_HOT_SIGMAV if you want to use high-temperature ($>10^{9}K$) reaction rates (otherwise don't calculate them, because it's slower). Enable NUCSYN_THERMALIZED_CORRECTIONS for high temperature reactions (not normally required).
• Enable NUCSYN_ALLOW_NO_PRODUCTION to prevent the surface abundances from changing if --no_production is used on the command line.
• NUCSYN_LOW_MASS_STRIPPING is used to change surface abundances as a function of mass stripped for star 1 and only for low mass. It is based on a lookup table of TWIN-code results. It is a temporary fudge for a particular problem and you probably do not want it.
• There are various logging options. NUCSYN_LOGGING should be defined if you want any output at all.
• NUCSYN_YIELDS should be used if you want to calculate the yield from each star. Note that yields are calculated for each single star and the whole binary system separately.
• NUCSYN_LOG_BINARY_MPYIELDS outputs the yield $p_M$ for the binary system (if NUCSYN_YIELDS and NUCSYN_LOG_YIELDS are defined).
• NUCSYN_LOG_YIELDS outputs the yields at every timestep (warning! this is a lot of output since it applies to all the isotopes, perhaps run through gawk to reduce the output) if NUCSYN_YIELDS is defined. If NUCSYN_YIELDS is defined and NUCSYN_LOG_YIELDS is not defined then the yields will be output at the end of the evolution time – this is the usual case.
• NUCSYN_LOG_BINARY_X_YIELDS outputs the mass ejected from the binary.
• NUCSYN_LOG_SINGLE_X_YIELDS outputs the mass ejected from each star.
• NUCSYN_LOG_MPYIELDS outputs the $p_M$ yield for each star.
• NUCSYN_LOG_DX_YIELDS outputs the mass ejected from each star for each timestep.
• NUCSYN_SHORT_LOG outputs some stuff about the stars (usually in the TPAGB phase)
• NUCSYN_LOG outputs more stuff.
• NUCSYN_LONG_LOG outputs even more stuff.
• NUCSYN_J_LOG outputs some stuff for J-type stars.
• NUCSYN_S_PROCESS_LOG outputs some stuff to do with the s-process.
• NUCSYN_STRUCTURE_LOG outputs stuff to do with the stellar structure.
• NUCSYN_XTOT_CHECKS is supposed to check that ${\Sigma }_i{X}_i=1$ (i.e. the mass fractions add to $1$) all the time. This has not been used in a long time… so do not be surprised if it fails!
• NUCSYN_CEMP_LOGGING and associated options are for the CEMP papers. Do not use these, they are experimental.
• NUCSYN_PLANETARY_NEBULAE provides some information about PNe formation.
• NUCSYN_TPAGB_RUNTIME provides information about the time the code spends in the nucsyn_tpagb function.
• NUCSYN_ID_SOURCES is used to identify where the yields come from and is extremely useful.
• CONSMASS is activated to check whether mass is conserved when a call is made to the nucsyn_binary_yield function. If you find you are losing mass somewhere then this is probably a bug (or a numerical error, in which case you should try to fix it!) so activate CONSMASS and the code will dump out when there is missing mass. See the nucsyn_binary_yield function for details. CONSMASSDM is an extension to this but I cannot remember what it does.
• MIXDEBUG outputs some debugging information in the mixing routines, but there's a lot of data... MIXLOG is supposed to be a shorter version but I haven't used this for ages so it might not work. MIXDEBUG is usually set in the routine you are considering rather than here because if it is activated in nucsyn.h then it will be passed to all routines.
• AMU_GRAMS and ANU_MEV are constants and should not be changed! They give the atomic mass unit in grams and MeV.
• NUC_MASSES_DEBUG enables debugging in the nuclear mass setting code.
• NUCSYN_TPAGB_EDDINGTON_CHECKS does something to tell you whether your AGB star exceeds the Eddington limit.
• NUCSYN_GCE enables other options which are used in my GCE code. Do not touch this unless you know what you are doing.
• NUCSYN_ROTATION_EFFECTS simulates extra ${}^{14}N$ production at low-$Z$. Do not touch.
• NUCSYN_HUGE_PULSE_CRISTALLO Enables a huge third dredge up based on Sergio Cristallo's models. Experimental.
• NUCSYN_CONVECTIVE_MIXIN Instead of mixing material into the whole envelope (as the original thermohaline mixing routine does) this uses the estimate of the convective envelope given in mrenv and mixes into that instead. Requires that you turn off thermohaline mixing (see MAYBE_NO_THERMOHALINE_MIXING and the --no_thermohaline_mixing 1 command-line option).
• NUCSYN_STAR_BY_STAR_MATCHING Enables some code to match stars to given observations.
• NUCSYN_SAFE_XSURF is defined if there is no possibility of a feedback loop which used to occur in the nucsyn_WR functions. Newer versions avoid this by using NUCSYN_WR_TABLES and so it should defined if NUCSYN_WR_TABLES is defined.
• NUCSYN_MU_FUZZ blurs the condition for accretion layers to sink to prevent unecessary calculations.
• MATTSSON_MASS_LOSS experimental mass-loss rates from Lars Mattsson (based on carbon abundances).
• LITHIUM_TABLES experiments to introduce lithium as a function of mass and pulse number in HBBing stars.

10.7 Colours in binary_c output

$ ./binary_c version | grep ANSI

$ ANSI colour 0 BLACK : Default is [0;30m, we are using [0;30m.
$ ANSI colour 1 RED : Default is [0;31m, we are using [0;31m.
$ ANSI colour 2 GREEN : Default is [0;32m, we are using [0;32m.
$ ...

$ ./binary_c colour2 12

$ ./binary_c ... colour_log False

11 binary_c software development

11.1 The git revolution

11.2 The \mainbranch (trunk)–branch model

git clone git@gitlab.com:binary_c/binary_c.git

git clone https://gitlab.com/binary_c/binary_c.git

11.2.1 Updating with the latest fixes

git merge

11.2.2 Committing your changes

git commit 

git commit -a

11.2.3 Submitting changes to the \mainbranch

• Run
  

  git pull

  
  to make sure you have the latest version of your code.
• Test your code to make sure it works as you expect.
• Run
  

  git commit -a

  
  to commit your code. Note that this does not send any information to the server, it is all done offline until you push you code (see below).
• Run
  

  git merge

  
  to merge all the latest changes into your code.
• Fix any conflicts, test the code, make sure it works as you expect even with the latest changes to the trunk.
• Run
  

  git push

  
  to send code to the server.
• Email Rob, tell him your branch is ready to commit, and tell him the git revision number of your last commit. You can also submit merge requests via the gitlab interface.

11.2.4 Getting your old code back

git revert 

11.3 Unit testing

11.3.1 Unit test arguments

11.3.2 Unit test reference data

11.3.3 Running unit tests

cd $BINARY_C
./src/python/do_unit_tests.py

11.3.4 How unit testing works

12 Cookbook

12.1 How to log output

Printf();

12.2 How to find which source files contain a string

$ ./rgrep <string> {opts}

$ ./rgrep <string> -i

12.3 How to build with debugging output

12.4 How to check for NaNs (not a numbers)

12.5 How to exit binary_c

Exit_binary_c(PIPE_FAILURE, “My pipe failed! ARGH!”);

12.6 How to debug segfaults

$ cd builddir
$ meson setup --reconfigure --buildtype=debug
$ ninja binary_c_install
$ cd ..

$ tbse debug 

12.7 How to debug memory leaks

$ cd builddir
$ meson setup --reconfigure --buildtype=debug -Dvalgrind=true
$ ninja binary_c_install
$ cd ..

$ tbse valgrind

$ tbse callgrind

$ tbse cachegrind

$ tbse ptrcheck

$ tbse sgcheck

12.8 How to show the arguments that tbse would use, but do not evolve a star

$ tbse echo

12.9 How to run a star which has the arguments in a file

$ tbse <filename>

12.10 How to use profile-guided optimization (PGO)

./meson/pgo.sh 1000

12.11 How to get help

12.11.1 How to know what a parameter does

$ binary_c help <parameter_name>

$ binary_c help_all

12.11.2 The mailing lists

12.12 How to add a parameter to binary_c

12.13 How to build on a Mac

12.14 How to build as a shared library

12.15 How to calculate stellar yields or population statistics

1. You have to build binary_c with NUCSYN and NUCSYN_GCE enabled, as well as the required physics
2. You have to install $binary\_c-python$.
3. Run an ensemble. See 7 for instructions.

12.16 bash autocompletion of binary_c arguments

# completion of binary_c arguments
_binary_c()
{
    COMPREPLY=()
    cmd="${COMP_WORDS[0]}"
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"
    binary_c_opts=$($BINARY_C_ROOT/binary_c help |/bin/grep -A2 "where the arguments are a selection of :"|tail -1|tr " " "\n")
    # check if we match a binary_c argument
    subcmd=( $(compgen -W "$binary_c_opts" "$prev") )
    if [[ $subcmd ]] ; then
        # we do match an argument : try to get sub options
        subopts=$($BINARY_C_ROOT/binary_c argopts $subcmd)
        COMPREPLY=( $(compgen -W "$subopts" -- ${cur}) )
    else
        # we don't, so list the arguments
        COMPREPLY=( $(compgen -W "$binary_c_opts" -- ${cur}) )
    fi
    return 0
}
complete -F _binary_c binary_c
complete -F _binary_c tbse

12.17

How to find the git revision and git URL

# git function for review number
git_rev ()
{
    d=`date +%Y%m%d`
    c=`git rev-list --full-history --all --abbrev-commit | wc -l | sed -e 's/^ *//'`
    h=`git rev-list --full-history --all --abbrev-commit | head -1`
    echo ${c}:${d}:${h}
}

# git function to find the repository url
git_url ()
{
    git config --get remote.origin.url
}

12.18 Ninja autocompletion

chmod +x bash_ninja_autocomplete.sh

# autocomplete for ninja source 
<path to file>/bash_ninja_autocomplete.sh 

12.19 Meson autocompletion

_filedir: command not found

if [ -n "$BASH_VERSION" ]; then
    [ -f /etc/bash_completion ] && . /etc/bash_completion
fi

12.20 Clang static analyzer (scan-build)

rm -r builddir # may not be necessary
mkdir scan_build_results_ninja scan_build_results_meson
scan-build -o scan_build_results_meson -v  meson setup builddir -Dusepch=false 2>&1 > scan.meson 
cd builddir
scan-build -o ../scan_build_results_ninja ninja -v 2>&1 > ../scan.ninja

12.21 Memory leak or memory bloat?

$ ./binary_c version |grep BUFFERED_PRINTF_MAX_BUFFER_SIZE

13 Changelog

Version 2.2

Stellar population ensembles using libcdict. Many code improvements (e.g. interaction with the YBC library). $binary\_c-python$ and (many) associated tools. Deprecated binary_grid.

Version 2.1

Time integration is now forward-Euler, RK2 or RK4, rationalised the time evolution loop, events subsystem introduced, fixed timesteps now standard, command line macros, update mass transfer rates, many bug fixes.

Version 2.0

Finally, RGI had some time to sit down and redesign the guts of binary_c. Version 2.0 is a cleaned up, sensible version of the old code. It has better logic, naming, time resolution, setup, etc.

Version 1.2prexx

Lots of updates! CEMPs project (Utrecht), experimental stuff to better model rotation, tables replace many fits (e.g. nucsyn_WR), interaction with binary_grid Perl module for population synthesis, external users (Selma, Joke, Carlo).

Version 1.2

Include STPAGB stars, batchmode and grid.pl references, spiky_luminosity, removal of the adaptive grid. Also mention gce.pl.

Version 1.1

Minor changes to include support for variation of initial abundances via command-line switches for Hilke's GCE project.

Version 1.0

The original version.

14 Acknowledgements